The AWS SDK for .NET V3 has entered maintenance mode.
We recommend that you migrate to [AWS SDK for .NET V4](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/welcome.html). For additional details and information on how to migrate, please refer to our [maintenance mode announcement](https://aws.amazon.com/blogs/developer/aws-sdk-for-net-v3-maintenance-mode-announcement/).
# Code examples with guidance for the AWS SDK for .NET
The following sections contain code examples and provide guidance for the examples. They can help you learn how to use the AWS SDK for .NET to work with AWS services.
If you're new to the AWS SDK for .NET, you might want to check out the [Take a quick tour](quick-start.md) topic first. It gives you an introduction to the SDK.
Before you begin, be sure you have [set up your environment and project](net-dg-config.md). Also review the information in [SDK features](net-dg-sdk-features.md).
**Topics**
+ [CloudFormation](cloudformation-apis-intro.md)
+ [Amazon Cognito](cognito-apis-intro.md)
+ [DynamoDB](dynamodb-intro.md)
+ [Amazon EC2](ec2-apis-intro.md)
+ [IAM](iam-apis-intro.md)
+ [Amazon S3](s3-apis-intro.md)
+ [Amazon SNS](sns-apis-intro.md)
+ [Amazon SQS](sqs-apis-intro.md)
# Accessing CloudFormation with the AWS SDK for .NET
The AWS SDK for .NET supports [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/), which creates and provisions AWS infrastructure deployments predictably and repeatedly.
## APIs
The AWS SDK for .NET provides APIs for CloudFormation clients. The APIs enable you to work with CloudFormation features such as templates and stacks. This section contains a small number of examples that show you the patterns you can follow when working with these APIs. To view the full set of APIs, see the [AWS SDK for .NET API Reference](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/) (and scroll to "Amazon.CloudFormation").
The AWS CloudFormation APIs are provided by the [AWSSDK.CloudFormation](https://www.nuget.org/packages/AWSSDK.CloudFormation/) package.
## Prerequisites
Before you begin, be sure you have [set up your environment and project](net-dg-config.md). Also review the information in [SDK features](net-dg-sdk-features.md).
## Topics
**Topics**
+ [APIs](#w2aac19c15c11b5)
+ [Prerequisites](#w2aac19c15c11b7)
+ [Topics](#w2aac19c15c11b9)
+ [Listing AWS resources](cfn-list-resources.md)
# Listing AWS resources using AWS CloudFormation
This example shows you how to use the AWS SDK for .NET to list the resources in CloudFormation stacks. The example uses the low-level API. The application takes no arguments, but simply gathers information for all stacks that are accessible to the user's credentials and then displays information about those stacks.
## SDK references
NuGet packages:
+ [AWSSDK.CloudFormation](https://www.nuget.org/packages/AWSSDK.CloudFormation/)
Programming elements:
+ Namespace [Amazon.CloudFormation](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CloudFormation/NCloudFormation.html)
Class [AmazonCloudFormationClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CloudFormation/TCloudFormationClient.html)
+ Namespace [Amazon.CloudFormation.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CloudFormation/NCloudFormationModel.html)
Class [ICloudFormationPaginatorFactory.DescribeStacks](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CloudFormation/MICloudFormationPaginatorFactoryDescribeStacksDescribeStacksRequest.html)
Class [DescribeStackResourcesRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CloudFormation/TDescribeStackResourcesRequest.html)
Class [DescribeStackResourcesResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CloudFormation/TDescribeStackResourcesResponse.html)
Class [Stack](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CloudFormation/TStack.html)
Class [StackResource](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CloudFormation/TStackResource.html)
Class [Tag](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CloudFormation/TTag.html)
```
using Amazon.CloudFormation;
using Amazon.CloudFormation.Model;
using Amazon.Runtime;
namespace CloudFormationActions;
public static class HelloCloudFormation
{
public static IAmazonCloudFormation _amazonCloudFormation;
static async Task Main(string[] args)
{
// Create the CloudFormation client
_amazonCloudFormation = new AmazonCloudFormationClient();
Console.WriteLine($"\nIn Region: {_amazonCloudFormation.Config.RegionEndpoint}");
// List the resources for each stack
await ListResources();
}
///
/// Method to list stack resources and other information.
///
/// True if successful.
public static async Task ListResources()
{
try
{
Console.WriteLine("Getting CloudFormation stack information...");
// Get all stacks using the stack paginator.
var paginatorForDescribeStacks =
_amazonCloudFormation.Paginators.DescribeStacks(
new DescribeStacksRequest());
await foreach (Stack stack in paginatorForDescribeStacks.Stacks)
{
// Basic information for each stack
Console.WriteLine("\n------------------------------------------------");
Console.WriteLine($"\nStack: {stack.StackName}");
Console.WriteLine($" Status: {stack.StackStatus.Value}");
Console.WriteLine($" Created: {stack.CreationTime}");
// The tags of each stack (etc.)
if (stack.Tags.Count > 0)
{
Console.WriteLine(" Tags:");
foreach (Tag tag in stack.Tags)
Console.WriteLine($" {tag.Key}, {tag.Value}");
}
// The resources of each stack
DescribeStackResourcesResponse responseDescribeResources =
await _amazonCloudFormation.DescribeStackResourcesAsync(
new DescribeStackResourcesRequest
{
StackName = stack.StackName
});
if (responseDescribeResources.StackResources.Count > 0)
{
Console.WriteLine(" Resources:");
foreach (StackResource resource in responseDescribeResources
.StackResources)
Console.WriteLine(
$" {resource.LogicalResourceId}: {resource.ResourceStatus}");
}
}
Console.WriteLine("\n------------------------------------------------");
return true;
}
catch (AmazonCloudFormationException ex)
{
Console.WriteLine("Unable to get stack information:\n" + ex.Message);
return false;
}
catch (AmazonServiceException ex)
{
if (ex.Message.Contains("Unable to get IAM security credentials"))
{
Console.WriteLine(ex.Message);
Console.WriteLine("If you are usnig SSO, be sure to install" +
" the AWSSDK.SSO and AWSSDK.SSOOIDC packages.");
}
else
{
Console.WriteLine(ex.Message);
Console.WriteLine(ex.StackTrace);
}
return false;
}
catch (ArgumentNullException ex)
{
if (ex.Message.Contains("Options property cannot be empty: ClientName"))
{
Console.WriteLine(ex.Message);
Console.WriteLine("If you are using SSO, have you logged in?");
}
else
{
Console.WriteLine(ex.Message);
Console.WriteLine(ex.StackTrace);
}
return false;
}
}
```
# Authenticating users with Amazon Cognito
**Note**
The information in this topic is specific to projects based on .NET Framework and the AWS SDK for .NET version 3.3 and earlier.
Using Amazon Cognito Identity, you can create unique identities for your users and authenticate them for secure access to your AWS resources such as Amazon S3 or Amazon DynamoDB. Amazon Cognito Identity supports public identity providers such as Amazon, Facebook, Twitter/Digits, Google, or any OpenID Connect-compatible provider as well as unauthenticated identities. Amazon Cognito also supports [developer authenticated identities](https://aws.amazon.com/blogs/mobile/amazon-cognito-announcing-developer-authenticated-identities/), which let you register and authenticate users using your own backend authentication process, while still using Amazon Cognito Sync to synchronize user data and access AWS resources.
For more information on [Amazon Cognito](https://aws.amazon.com/cognito/), see the [Amazon Cognito Developer Guide](https://docs.aws.amazon.com/cognito/latest/developerguide/).
The following code examples show how to easily use Amazon Cognito Identity. The [Credentials provider](cognito-creds-provider.md) example shows how to create and authenticate user identities. The [CognitoAuthentication extension library](cognito-authentication-extension.md) example shows how to use the CognitoAuthentication extension library to authenticate Amazon Cognito user pools.
**Topics**
+ [Credentials provider](cognito-creds-provider.md)
+ [CognitoAuthentication extension library](cognito-authentication-extension.md)
# Amazon Cognito credentials provider
**Note**
The information in this topic is specific to projects based on .NET Framework and the AWS SDK for .NET version 3.3 and earlier.
`Amazon.CognitoIdentity.CognitoAWSCredentials`, found in the [AWSSDK.CognitoIdentity](https://www.nuget.org/packages/AWSSDK.CognitoIdentity/) NuGet package, is a credentials object that uses Amazon Cognito and the AWS Security Token Service (AWS STS) to retrieve credentials to make AWS calls.
The first step in setting up `CognitoAWSCredentials` is to create an “identity pool”. (An identity pool is a store of user identity information that is specific to your account. The information is retrievable across client platforms, devices, and operating systems, so that if a user starts using the app on a phone and later switches to a tablet, the persisted app information is still available for that user. You can create a new identity pool from the Amazon Cognito console. If you are using the console, it will also provide you the other pieces of information you need:
+ Your account number- A 12-digit number, such as 123456789012, that is unique to your account.
+ The unauthenticated role ARN- A role that unauthenticated users will assume. For example, this role can provide read-only permissions to your data.
+ The authenticated role ARN- A role that authenticated users will assume. This role can provide more extensive permissions to your data.
## Set up CognitoAWSCredentials
The following code example shows how to set up `CognitoAWSCredentials`, which you can then use to make a call to Amazon S3 as an unauthenticated user. This enables you to make calls with just a minimum amount of data required to authenticate the user. User permissions are controlled by the role, so you can configure access as you need.
```
CognitoAWSCredentials credentials = new CognitoAWSCredentials(
accountId, // Account number
identityPoolId, // Identity pool ID
unAuthRoleArn, // Role for unauthenticated users
null, // Role for authenticated users, not set
region);
using (var s3Client = new AmazonS3Client(credentials))
{
s3Client.ListBuckets();
}
```
## Use AWS as an unauthenticated user
The following code example shows how you can start using AWS as an unauthenticated user, then authenticate through Facebook and update the credentials to use Facebook credentials. Using this approach, you can grant different capabilities to authenticated users via the authenticated role. For instance, you might have a phone application that permits users to view content anonymously, but allows them to post if they are logged on with one or more of the configured providers.
```
CognitoAWSCredentials credentials = new CognitoAWSCredentials(
accountId, identityPoolId,
unAuthRoleArn, // Role for unauthenticated users
authRoleArn, // Role for authenticated users
region);
using (var s3Client = new AmazonS3Client(credentials))
{
// Initial use will be unauthenticated
s3Client.ListBuckets();
// Authenticate user through Facebook
string facebookToken = GetFacebookAuthToken();
// Add Facebook login to credentials. This clears the current AWS credentials
// and retrieves new AWS credentials using the authenticated role.
credentials.AddLogin("graph.facebook.com", facebookAccessToken);
// This call is performed with the authenticated role and credentials
s3Client.ListBuckets();
}
```
The `CognitoAWSCredentials` object provides even more functionality if you use it with the `AmazonCognitoSyncClient` that is part of the AWS SDK for .NET. If you're using both `AmazonCognitoSyncClient` and `CognitoAWSCredentials`, you don't have to specify the `IdentityPoolId` and `IdentityId` properties when making calls with the `AmazonCognitoSyncClient`. These properties are automatically filled in from `CognitoAWSCredentials`. The next code example illustrates this, as well as an event that notifies you whenever the `IdentityId` for `CognitoAWSCredentials` changes. The `IdentityId` can change in some cases, such as when changing from an unauthenticated user to an authenticated one.
```
CognitoAWSCredentials credentials = GetCognitoAWSCredentials();
// Log identity changes
credentials.IdentityChangedEvent += (sender, args) =>
{
Console.WriteLine("Identity changed: [{0}] => [{1}]", args.OldIdentityId, args.NewIdentityId);
};
using (var syncClient = new AmazonCognitoSyncClient(credentials))
{
var result = syncClient.ListRecords(new ListRecordsRequest
{
DatasetName = datasetName
// No need to specify these properties
//IdentityId = "...",
//IdentityPoolId = "..."
});
}
```
# Amazon CognitoAuthentication extension library examples
**Note**
The information in this topic is specific to projects based on .NET Framework and the AWS SDK for .NET version 3.3 and earlier.
The CognitoAuthentication extension library, found in the [Amazon.Extensions.CognitoAuthentication](https://www.nuget.org/packages/Amazon.Extensions.CognitoAuthentication/) NuGet package, simplifies the authentication process of Amazon Cognito user pools for .NET Core and Xamarin developers. The library is built on top of the Amazon Cognito Identity provider API to create and send user authentication API calls.
## Using the CognitoAuthentication extension library
Amazon Cognito has some built-in `AuthFlow` and `ChallengeName` values for a standard authentication flow to validate username and password through the Secure Remote Password (SRP). For more information about authentication flow, see [Amazon Cognito User Pool Authentication Flow](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-authentication-flow.html).
The following examples require these `using` statements:
```
// Required for all examples
using System;
using Amazon;
using Amazon.CognitoIdentity;
using Amazon.CognitoIdentityProvider;
using Amazon.Extensions.CognitoAuthentication;
using Amazon.Runtime;
// Required for the GetS3BucketsAsync example
using Amazon.S3;
using Amazon.S3.Model;
```
### Use basic authentication
Create an [AmazonCognitoIdentityProviderClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CognitoIdentityProvider/TCognitoIdentityProviderClient.html) using [AnonymousAWSCredentials](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/Runtime/TAnonymousAWSCredentials.html), which do not require signed requests. You do not need to supply a region, the underlying code calls `FallbackRegionFactory.GetRegionEndpoint()` if a region is not provided. Create `CognitoUserPool` and `CognitoUser` objects. Call the `StartWithSrpAuthAsync` method with an `InitiateSrpAuthRequest` that contains the user password.
```
public static async void GetCredsAsync()
{
AmazonCognitoIdentityProviderClient provider =
new AmazonCognitoIdentityProviderClient(new Amazon.Runtime.AnonymousAWSCredentials());
CognitoUserPool userPool = new CognitoUserPool("poolID", "clientID", provider);
CognitoUser user = new CognitoUser("username", "clientID", userPool, provider);
InitiateSrpAuthRequest authRequest = new InitiateSrpAuthRequest()
{
Password = "userPassword"
};
AuthFlowResponse authResponse = await user.StartWithSrpAuthAsync(authRequest).ConfigureAwait(false);
accessToken = authResponse.AuthenticationResult.AccessToken;
}
```
### Authenticate with challenges
Continuing the authentication flow with challenges, such as with NewPasswordRequired and Multi-Factor Authentication (MFA), is also simpler. The only requirements are the CognitoAuthentication objects, user's password for SRP, and the necessary information for the next challenge, which is acquired after prompting the user to enter it. The following code shows one way to check the challenge type and get the appropriate responses for MFA and NewPasswordRequired challenges during the authentication flow.
Do a basic authentication request as before, and `await` an `AuthFlowResponse`. When the response is received loop through the returned `AuthenticationResult` object. If the `ChallengeName` type is `NEW_PASSWORD_REQUIRED`, call the `RespondToNewPasswordRequiredAsync` method.
```
public static async void GetCredsChallengesAsync()
{
AmazonCognitoIdentityProviderClient provider =
new AmazonCognitoIdentityProviderClient(new Amazon.Runtime.AnonymousAWSCredentials());
CognitoUserPool userPool = new CognitoUserPool("poolID", "clientID", provider);
CognitoUser user = new CognitoUser("username", "clientID", userPool, provider);
InitiateSrpAuthRequest authRequest = new InitiateSrpAuthRequest(){
Password = "userPassword"
};
AuthFlowResponse authResponse = await user.StartWithSrpAuthAsync(authRequest).ConfigureAwait(false);
while (authResponse.AuthenticationResult == null)
{
if (authResponse.ChallengeName == ChallengeNameType.NEW_PASSWORD_REQUIRED)
{
Console.WriteLine("Enter your desired new password:");
string newPassword = Console.ReadLine();
authResponse = await user.RespondToNewPasswordRequiredAsync(new RespondToNewPasswordRequiredRequest()
{
SessionID = authResponse.SessionID,
NewPassword = newPassword
});
accessToken = authResponse.AuthenticationResult.AccessToken;
}
else if (authResponse.ChallengeName == ChallengeNameType.SMS_MFA)
{
Console.WriteLine("Enter the MFA Code sent to your device:");
string mfaCode = Console.ReadLine();
AuthFlowResponse mfaResponse = await user.RespondToSmsMfaAuthAsync(new RespondToSmsMfaRequest()
{
SessionID = authResponse.SessionID,
MfaCode = mfaCode
}).ConfigureAwait(false);
accessToken = authResponse.AuthenticationResult.AccessToken;
}
else
{
Console.WriteLine("Unrecognized authentication challenge.");
accessToken = "";
break;
}
}
if (authResponse.AuthenticationResult != null)
{
Console.WriteLine("User successfully authenticated.");
}
else
{
Console.WriteLine("Error in authentication process.");
}
}
```
### Use AWS resources after authentication
Once a user is authenticated using the CognitoAuthentication library, the next step is to allow the user to access the appropriate AWS resources. To do this you must create an identity pool through the Amazon Cognito Federated Identities console. By specifying the Amazon Cognito user pool you created as a provider, using its poolID and clientID, you can allow your Amazon Cognito user pool users to access AWS resources connected to your account. You can also specify different roles to enable both unauthenticated and authenticated users to access different resources. You can change these rules in the IAM console, where you can add or remove permissions in the **Action** field of the role's attached policy. Then, using the appropriate identity pool, user pool, and Amazon Cognito user information, you can make calls to different AWS resources. The following example shows a user authenticated with SRP accessing the different Amazon S3 buckets permitted by the associated identity pool's role
```
public async void GetS3BucketsAsync()
{
var provider = new AmazonCognitoIdentityProviderClient(new AnonymousAWSCredentials());
CognitoUserPool userPool = new CognitoUserPool("poolID", "clientID", provider);
CognitoUser user = new CognitoUser("username", "clientID", userPool, provider);
string password = "userPassword";
AuthFlowResponse context = await user.StartWithSrpAuthAsync(new InitiateSrpAuthRequest()
{
Password = password
}).ConfigureAwait(false);
CognitoAWSCredentials credentials =
user.GetCognitoAWSCredentials("identityPoolID", RegionEndpoint.< YourIdentityPoolRegion >);
using (var client = new AmazonS3Client(credentials))
{
ListBucketsResponse response =
await client.ListBucketsAsync(new ListBucketsRequest()).ConfigureAwait(false);
foreach (S3Bucket bucket in response.Buckets)
{
Console.WriteLine(bucket.BucketName);
}
}
}
```
## More authentication options
In addition to SRP, NewPasswordRequired, and MFA, the CognitoAuthentication extension library offers an easier authentication flow for:
+ Custom - Initiate with a call to `StartWithCustomAuthAsync(InitiateCustomAuthRequest customRequest)`
+ RefreshToken - Initiate with a call to `StartWithRefreshTokenAuthAsync(InitiateRefreshTokenAuthRequest refreshTokenRequest)`
+ RefreshTokenSRP - Initiate with a call to `StartWithRefreshTokenAuthAsync(InitiateRefreshTokenAuthRequest refreshTokenRequest)`
+ AdminNoSRP - Initiate with a call to `StartWithAdminNoSrpAuthAsync(InitiateAdminNoSrpAuthRequest adminAuthRequest)`
Call the appropriate method depending on the flow you want. Then continue prompting the user with challenges as they are presented in the `AuthFlowResponse` objects of each method call. Also call the appropriate response method, such as `RespondToSmsMfaAuthAsync` for MFA challenges and `RespondToCustomAuthAsync` for custom challenges.
# Using Amazon DynamoDB NoSQL databases
**Note**
The programming models in these topics are present in both .NET Framework and .NET (Core), but the calling conventions differ, whether synchronous or asynchronous.
The AWS SDK for .NET supports Amazon DynamoDB, which is a fast NoSQL database service offered by AWS. The SDK provides three programming models for communicating with DynamoDB: the *low-level* model, the *document* model, and the *object persistence* model.
The following information introduces these models and their APIs, provides examples for how and when to use them, and gives you links to additional DynamoDB programming resources in the AWS SDK for .NET.
## Low-Level Model
The low-level programming model wraps direct calls to the DynamoDB service. You access this model through the [Amazon.DynamoDBv2](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/DynamoDBv2/NDynamoDBv2.html) namespace.
Of the three models, the low-level model requires you to write the most code. For example, you must convert .NET data types to their equivalents in DynamoDB. However, this model gives you access to the most features.
The following examples show you how to use the low-level model to create a table, modify a table, and insert items into a table in DynamoDB.
### Creating a Table
In the following example, you create a table by using the `CreateTable` method of the `AmazonDynamoDBClient` class. The `CreateTable` method uses an instance of the `CreateTableRequest` class that contains characteristics such as required item attribute names, primary key definition, and throughput capacity. The `CreateTable` method returns an instance of the `CreateTableResponse` class.
```
// using Amazon.DynamoDBv2;
// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient();
Console.WriteLine("Getting list of tables");
List currentTables = client.ListTables().TableNames;
Console.WriteLine("Number of tables: " + currentTables.Count);
if (!currentTables.Contains("AnimalsInventory"))
{
var request = new CreateTableRequest
{
TableName = "AnimalsInventory",
AttributeDefinitions = new List
{
new AttributeDefinition
{
AttributeName = "Id",
// "S" = string, "N" = number, and so on.
AttributeType = "N"
},
new AttributeDefinition
{
AttributeName = "Type",
AttributeType = "S"
}
},
KeySchema = new List
{
new KeySchemaElement
{
AttributeName = "Id",
// "HASH" = hash key, "RANGE" = range key.
KeyType = "HASH"
},
new KeySchemaElement
{
AttributeName = "Type",
KeyType = "RANGE"
},
},
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = 10,
WriteCapacityUnits = 5
},
};
var response = client.CreateTable(request);
Console.WriteLine("Table created with request ID: " +
response.ResponseMetadata.RequestId);
}
```
### Verifying That a Table is Ready to Modify
Before you can change or modify a table, the table has to be ready for modification. The following example shows how to use the low-level model to verify that a table in DynamoDB is ready. In this example, the target table to check is referenced through the `DescribeTable` method of the `AmazonDynamoDBClient` class. Every five seconds, the code checks the value of the table’s `TableStatus` property. When the status is set to `ACTIVE`, the table is ready to be modified.
```
// using Amazon.DynamoDBv2;
// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient();
var status = "";
do
{
// Wait 5 seconds before checking (again).
System.Threading.Thread.Sleep(TimeSpan.FromSeconds(5));
try
{
var response = client.DescribeTable(new DescribeTableRequest
{
TableName = "AnimalsInventory"
});
Console.WriteLine("Table = {0}, Status = {1}",
response.Table.TableName,
response.Table.TableStatus);
status = response.Table.TableStatus;
}
catch (ResourceNotFoundException)
{
// DescribeTable is eventually consistent. So you might
// get resource not found.
}
} while (status != TableStatus.ACTIVE);
```
### Inserting an Item into a Table
In the following example, you use the low-level model to insert two items into a table in DynamoDB. Each item is inserted through the `PutItem` method of the `AmazonDynamoDBClient` class, using an instance of the `PutItemRequest` class. Each of the two instances of the `PutItemRequest` class takes the name of the table that the items will be inserted in, with a series of item attribute values.
```
// using Amazon.DynamoDBv2;
// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient();
var request1 = new PutItemRequest
{
TableName = "AnimalsInventory",
Item = new Dictionary
{
{ "Id", new AttributeValue { N = "1" }},
{ "Type", new AttributeValue { S = "Dog" }},
{ "Name", new AttributeValue { S = "Fido" }}
}
};
var request2 = new PutItemRequest
{
TableName = "AnimalsInventory",
Item = new Dictionary
{
{ "Id", new AttributeValue { N = "2" }},
{ "Type", new AttributeValue { S = "Cat" }},
{ "Name", new AttributeValue { S = "Patches" }}
}
};
client.PutItem(request1);
client.PutItem(request2);
```
## Document Model
The document programming model provides an easier way to work with data in DynamoDB. This model is specifically intended for accessing tables and items in tables. You access this model through the [Amazon.DynamoDBv2.DocumentModel](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/DynamoDBv2/NDynamoDBv2DocumentModel.html) namespace.
Compared to the low-level programming model, the document model is easier to code against DynamoDB data. For example, you don’t have to convert as many .NET data types to their equivalents in DynamoDB. However, this model doesn’t provide access to as many features as the low-level programming model. For example, you can use this model to create, retrieve, update, and delete items in tables. However, to create the tables, you must use the low-level model. Compared to the object persistence model, this model requires you to write more code to store, load, and query .NET objects.
For more information about the DynamoDB document programming model, see [.NET: Document model](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DotNetSDKMidLevel.html) in the [Amazon DynamoDB Developer Guide](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/).
The following sections provide information about how to create a representation of the desired DynamoDB table, and examples about how to use the document model to insert items into tables and get items from tables.
### Create a representation of the table
To perform data operations using the document model, you must first create an instance of the `Table` class that represents a specific table. There are two primary ways to do this.
**LoadTable method**
The first mechanism is to use one of the static `LoadTable` methods of the [https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/DynamoDBv2/TTable.html](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/DynamoDBv2/TTable.html) class, similar to the following example:
```
var client = new AmazonDynamoDBClient();
Table table = Table.LoadTable(client, "Reply");
```
**Note**
While this mechanism works, under certain conditions, it can sometimes lead to additional latency or deadlocks due to cold-start and thread-pool behaviors. For more information about these behaviors, see the blog post [Improved DynamoDB Initialization Patterns for the AWS SDK for .NET](https://aws.amazon.com/blogs/developer/improved-dynamodb-initialization-patterns-for-the-aws-sdk-for-net/).
**TableBuilder**
An alternative mechanism, the [https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/DynamoDBv2/TTableBuilder.html](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/DynamoDBv2/TTableBuilder.html) class, was introduced in [version 3.7.203 of the AWSSDK.DynamoDBv2 NuGet package](https://www.nuget.org/packages/AWSSDK.DynamoDBv2/3.7.203). This mechanism can address the behaviors mentioned above by removing certain implicit method calls; specifically, the `DescribeTable` method. This mechanism is used in a manner similar to the following example:
```
var client = new AmazonDynamoDBClient();
var table = new TableBuilder(client, "Reply")
.AddHashKey("Id", DynamoDBEntryType.String)
.AddRangeKey("ReplyDateTime", DynamoDBEntryType.String)
.AddGlobalSecondaryIndex("PostedBy-Message-index", "Author", DynamoDBEntryType.String, "Message", DynamoDBEntryType.String)
.Build();
```
For more information about this alternative mechanism, see again the blog post [Improved DynamoDB Initialization Patterns for the AWS SDK for .NET](https://aws.amazon.com/blogs/developer/improved-dynamodb-initialization-patterns-for-the-aws-sdk-for-net/).
### Inserting an item into a table
In the following example, a reply is inserted into the Reply table through the `PutItemAsync` method of the `Table` class. The `PutItemAsync` method takes an instance of the `Document` class; the `Document` class is simply a collection of initialized attributes.
```
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DocumentModel;
// Create a representation of the "Reply" table
// by using one of the mechanisms described previously.
// Then, add a reply to the table.
var newReply = new Document();
newReply["Id"] = Guid.NewGuid().ToString();
newReply["ReplyDateTime"] = DateTime.UtcNow;
newReply["PostedBy"] = "Author1";
newReply["Message"] = "Thank you!";
await table.PutItemAsync(newReply);
```
### Getting an item from a table
In the following example, a reply is retrieved through the `GetItemAsync` method of the `Table` class. To determine the reply to get, the `GetItemAsync` method uses the hash-and-range primary key of the target reply.
```
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DocumentModel;
// Create a representation of the "Reply" table
// by using one of the mechanisms described previously.
// Then, get a reply from the table
// where "guid" is the hash key and "datetime" is the range key.
var reply = await table.GetItemAsync(guid, datetime);
Console.WriteLine("Id = " + reply["Id"]);
Console.WriteLine("ReplyDateTime = " + reply["ReplyDateTime"]);
Console.WriteLine("PostedBy = " + reply["PostedBy"]);
Console.WriteLine("Message = " + reply["Message"]);
```
The preceding example implicitly converts the table values to strings for the `WriteLine` method. You can do explicit conversions by using the various "As[type]" methods of the `DynamoDBEntry` class. For example, you can explicitly convert the value for `Id` from a `Primitive` data type to a GUID through the `AsGuid()` method:
```
var guid = reply["Id"].AsGuid();
```
## Object Persistence Model
The object persistence programming model is specifically designed for storing, loading, and querying .NET objects in DynamoDB. You access this model through the [Amazon.DynamoDBv2.DataModel](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/DynamoDBv2/NDynamoDBv2DataModel.html) namespace.
Of the three models, the object persistence model is the easiest to code against whenever you are storing, loading, or querying DynamoDB data. For example, you work with DynamoDB data types directly. However, this model provides access only to operations that store, load, and query .NET objects in DynamoDB. For example, you can use this model to create, retrieve, update, and delete items in tables. However, you must first create your tables using the low-level model, and then use this model to map your .NET classes to the tables.
For more information about the DynamoDB object persistence programming model, see [.NET: Object persistence model](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DotNetSDKHighLevel.html) in the [Amazon DynamoDB Developer Guide](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/).
The following examples show you how to define a .NET class that represents a DynamoDB item, use an instance of the .NET class to insert an item into a DynamoDB table, and use an instance of the .NET class to get an item from the table.
### Defining a .NET class that represents an item in a table
In the following example of a class definition, the `DynamoDBTable` attribute specifies the table name, while the `DynamoDBHashKey` and `DynamoDBRangeKey` attributes model the table's hash-and-range primary key. The `DynamoDBGlobalSecondaryIndexHashKey` attribute is defined so that a query for replies by a specific author can be constructed.
```
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
[DynamoDBTable("Reply")]
public class Reply
{
[DynamoDBHashKey]
public string Id { get; set; }
[DynamoDBRangeKey(StoreAsEpoch = false)]
public DateTime ReplyDateTime { get; set; }
[DynamoDBGlobalSecondaryIndexHashKey("PostedBy-Message-Index",
AttributeName ="PostedBy")]
public string Author { get; set; }
[DynamoDBGlobalSecondaryIndexRangeKey("PostedBy-Message-Index")]
public string Message { get; set; }
}
```
### Creating a context for the object persistence model
To use the object persistence programming model for DynamoDB, you must create a context, which provides a connection to DynamoDB and enables you to access tables, perform various operations, and run queries.
**Basic context**
The following example shows how to create the most basic context.
```
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
var client = new AmazonDynamoDBClient();
var context = new DynamoDBContext(client);
```
**Context with DisableFetchingTableMetadata property**
The following example shows how you might additionally set the `DisableFetchingTableMetadata` property of the `DynamoDBContextConfig` class to prevent implicit calls to the `DescribeTable` method.
```
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
var client = new AmazonDynamoDBClient();
var context = new DynamoDBContext(client, new DynamoDBContextConfig
{
DisableFetchingTableMetadata = true
});
```
If the `DisableFetchingTableMetadata` property is set to `false` (the default), as shown in the first example, you can omit attributes that describe the key and index structure of table items from the `Reply` class. These attributes will instead be inferred through an implicit call to the `DescribeTable` method. If `DisableFetchingTableMetadata` is set to `true`, as shown in the second example, methods of the object persistence model such as `SaveAsync` and `QueryAsync` rely entirely on the attributes defined in the `Reply` class. In this case, a call to the `DescribeTable` method doesn't occur.
**Note**
Under certain conditions, calls to the `DescribeTable` method can sometimes lead to additional latency or deadlocks due to cold-start and thread-pool behaviors. For this reason, it is sometimes advantageous to avoid calls to that method.
For more information about these behaviors, see the blog post [Improved DynamoDB Initialization Patterns for the AWS SDK for .NET](https://aws.amazon.com/blogs/developer/improved-dynamodb-initialization-patterns-for-the-aws-sdk-for-net/).
### Using an instance of the .NET class to insert an item into a table
In this example, an item is inserted through the `SaveAsync` method of the `DynamoDBContext` class, which takes an initialized instance of the .NET class that represents the item.
```
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
// Create an appropriate context for the object persistence programming model,
// examples of which have been described earlier.
// Create an object that represents the new item.
var reply = new Reply()
{
Id = Guid.NewGuid().ToString(),
ReplyDateTime = DateTime.UtcNow,
Author = "Author1",
Message = "Thank you!"
};
// Insert the item into the table.
await context.SaveAsync(reply, new DynamoDBOperationConfig
{
IndexName = "PostedBy-Message-index"
});
```
### Using an instance of a .NET class to get items from a table
In this example, a query is created to find all the records of "Author1" by using the `QueryAsync` method of the `DynamoDBContext` class. Then, items are retrieved through the query's `GetNextSetAsync` method.
```
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
// Create an appropriate context for the object persistence programming model,
// examples of which have been described earlier.
// Construct a query that finds all replies by a specific author.
var query = context.QueryAsync("Author1", new DynamoDBOperationConfig
{
IndexName = "PostedBy-Message-index"
});
// Display the result.
var set = await query.GetNextSetAsync();
foreach (var item in set)
{
Console.WriteLine("Id = " + item.Id);
Console.WriteLine("ReplyDateTime = " + item.ReplyDateTime);
Console.WriteLine("PostedBy = " + item.Author);
Console.WriteLine("Message = " + item.Message);
}
```
### Additional information about the object persistence model
The examples and explanations shown above sometimes include a property of the `DynamoDBContext` class called `DisableFetchingTableMetadata`. This property, which was introduced in [version 3.7.203 of the AWSSDK.DynamoDBv2 NuGet package](https://www.nuget.org/packages/AWSSDK.DynamoDBv2/3.7.203), allows you to avoid certain conditions that might cause additional latency or deadlocks due to cold-start and thread-pool behaviors. For more information, see the blog post [Improved DynamoDB Initialization Patterns for the AWS SDK for .NET](https://aws.amazon.com/blogs/developer/improved-dynamodb-initialization-patterns-for-the-aws-sdk-for-net/).
The following is some additional information about this property.
+ This property can be set globally in your `app.config` or `web.config` file if you're using .NET Framework.
+ This property can be set globally by using the [https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/Amazon/TAWSConfigsDynamoDB.html](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/Amazon/TAWSConfigsDynamoDB.html) class, as shown in the following example.
```
// Set the DisableFetchingTableMetadata property globally
// before constructing any context objects.
AWSConfigsDynamoDB.Context.DisableFetchingTableMetadata = true;
var client = new AmazonDynamoDBClient();
var context = new DynamoDBContext(client);
```
+ In some cases, you can't add DynamoDB attributes to a .NET class; for example, if the class is defined in a dependency. In such cases, it's possible to still take advantage of the `DisableFetchingTableMetadata` property. To do so, use the [https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/DynamoDBv2/TTableBuilder.html](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/DynamoDBv2/TTableBuilder.html) class in addition to the `DisableFetchingTableMetadata` property. The `TableBuilder` class was also introduced in [version 3.7.203 of the AWSSDK.DynamoDBv2 NuGet package](https://www.nuget.org/packages/AWSSDK.DynamoDBv2/3.7.203).
```
// Set the DisableFetchingTableMetadata property globally
// before constructing any context objects.
AWSConfigsDynamoDB.Context.DisableFetchingTableMetadata = true;
var client = new AmazonDynamoDBClient();
var context = new DynamoDBContext(client);
var table = new TableBuilder(client, "Reply")
.AddHashKey("Id", DynamoDBEntryType.String)
.AddRangeKey("ReplyDateTime", DynamoDBEntryType.String)
.AddGlobalSecondaryIndex("PostedBy-Message-index", "Author", DynamoDBEntryType.String,
"Message", DynamoDBEntryType.String)
.Build();
// This registers the "Reply" table we constructed via the builder.
context.RegisterTableDefinition(table);
// Now operations like this will work,
// even if the Reply class was not annotated with this index.
var query = context.QueryAsync("Author1", new DynamoDBOperationConfig()
{
IndexName = "PostedBy-Message-index"
});
```
## More information
**Using the AWS SDK for .NET to program DynamoDB, information and examples**
+ [DynamoDB APIs](http://blogs.aws.amazon.com/net/post/Tx17SQHVEMW8MXC/DynamoDB-APIs)
+ [DynamoDB Series Kickoff](http://blogs.aws.amazon.com/net/post/Tx2XQOCY08QMTKO/DynamoDB-Series-Kickoff)
+ [DynamoDB Series - Document Model](http://blogs.aws.amazon.com/net/post/Tx2R0WG46GQI1JI/DynamoDB-Series-Document-Model)
+ [DynamoDB Series - Conversion Schemas](http://blogs.aws.amazon.com/net/post/Tx2TCOGWG7ARUH5/DynamoDB-Series-Conversion-Schemas)
+ [DynamoDB Series - Object Persistence Model](http://blogs.aws.amazon.com/net/post/Tx20L86FLMBW51P/DynamoDB-Series-Object-Persistence-Model)
+ [DynamoDB Series - Expressions](http://blogs.aws.amazon.com/net/post/TxZQM7VA9AUZ9L/DynamoDB-Series-Expressions)
+ [Using Expressions with Amazon DynamoDB and the AWS SDK for .NET](dynamodb-expressions.md)
+ [JSON support in Amazon DynamoDB](dynamodb-json.md)
**Low-Level model, information and examples**
+ [Working with Tables Using the AWS SDK for .NET Low-Level API](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LowLevelDotNetWorkingWithTables.html)
+ [Working with Items Using the AWS SDK for .NET Low-Level API](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LowLevelDotNetItemCRUD.html)
+ [Querying Tables Using the AWS SDK for .NET Low-Level API](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LowLevelDotNetQuerying.html)
+ [Scanning Tables Using the AWS SDK for .NET Low-Level API](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LowLevelDotNetScanning.html)
+ [Working with Local Secondary Indexes Using the AWS SDK for .NET Low-Level API](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LSILowLevelDotNet.html)
+ [Working with Global Secondary Indexes Using the AWS SDK for .NET Low-Level API](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSILowLevelDotNet.html)
**Document model, information and examples**
+ [DynamoDB Data Types](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DataModel.html#DataModel.DataTypes)
+ [DynamoDBEntry](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TDynamoDBv2DocumentModelDynamoDBEntry.html)
+ [.NET: Document Model](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DotNetSDKMidLevel.html)
**Object persistence model, information and examples**
+ [.NET: Object Persistence Model](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DotNetSDKHighLevel.html)
**Other useful information**
+ See [Integrating AWS with .NET Aspire](aspire-integrations.md) for information about developing with Amazon DynamoDB local through .NET Aspire.
**Topics**
+ [Low-Level Model](#dynamodb-intro-apis-low-level)
+ [Document Model](#dynamodb-intro-apis-document)
+ [Object Persistence Model](#dynamodb-intro-apis-object-persistence)
+ [More information](#dynamodb-intro-more-info)
+ [Using expressions](dynamodb-expressions.md)
+ [JSON support](dynamodb-json.md)
# Using Expressions with Amazon DynamoDB and the AWS SDK for .NET
**Note**
The information in this topic is specific to projects based on .NET Framework and the AWS SDK for .NET version 3.3 and earlier.
The following code examples demonstrate how to use the AWS SDK for .NET to program DynamoDB with expressions. *Expressions* denote the attributes you want to read from an item in a DynamoDB table. You also use expressions when writing an item, to indicate any conditions that must be met (also known as a *conditional update*) and how the attributes are to be updated. Some update examples are replacing the attribute with a new value, or adding new data to a list or a map. For more information, see [Reading and Writing Items Using Expressions](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.html).
**Topics**
+ [Sample Data](#dynamodb-expressions-sample-data)
+ [Get a Single Item by Using Expressions and the Item’s Primary Key](#dynamodb-expressions-get-item)
+ [Get Multiple Items by Using Expressions and the Table’s Primary Key](#dynamodb-expressions-query)
+ [Get Multiple Items by Using Expressions and Other Item Attributes](#dynamodb-expressions-scan)
+ [Print an Item](#dynamodb-expressions-print-item)
+ [Create or Replace an Item by Using Expressions](#dynamodb-expressions-put-item)
+ [Update an Item by Using Expressions](#dynamodb-expressions-update-item)
+ [Delete an Item by Using Expressions](#dynamodb-expressions-delete-item)
+ [More Info](#dynamodb-expressions-resources)
## Sample Data
The code examples in this topic rely on the following two example items in a DynamoDB table named `ProductCatalog`. These items describe information about product entries in a fictitious bicycle store catalog. These items are based on the example provided in [Case Study: A ProductCatalog Item](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.CaseStudy.html). The data type descriptors such as `BOOL`, `L`, `M`, `N`, `NS`, `S`, and `SS` correspond to those in the [JSON Data Format](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DataFormat.html).
```
{
"Id": {
"N": "205"
},
"Title": {
"S": "20-Bicycle 205"
},
"Description": {
"S": "205 description"
},
"BicycleType": {
"S": "Hybrid"
},
"Brand": {
"S": "Brand-Company C"
},
"Price": {
"N": "500"
},
"Gender": {
"S": "B"
},
"Color": {
"SS": [
"Red",
"Black"
]
},
"ProductCategory": {
"S": "Bike"
},
"InStock": {
"BOOL": true
},
"QuantityOnHand": {
"N": "1"
},
"RelatedItems": {
"NS": [
"341",
"472",
"649"
]
},
"Pictures": {
"L": [
{
"M": {
"FrontView": {
"S": "http://example/products/205_front.jpg"
}
}
},
{
"M": {
"RearView": {
"S": "http://example/products/205_rear.jpg"
}
}
},
{
"M": {
"SideView": {
"S": "http://example/products/205_left_side.jpg"
}
}
}
]
},
"ProductReviews": {
"M": {
"FiveStar": {
"SS": [
"Excellent! Can't recommend it highly enough! Buy it!",
"Do yourself a favor and buy this."
]
},
"OneStar": {
"SS": [
"Terrible product! Do not buy this."
]
}
}
}
},
{
"Id": {
"N": "301"
},
"Title": {
"S": "18-Bicycle 301"
},
"Description": {
"S": "301 description"
},
"BicycleType": {
"S": "Road"
},
"Brand": {
"S": "Brand-Company C"
},
"Price": {
"N": "185"
},
"Gender": {
"S": "F"
},
"Color": {
"SS": [
"Blue",
"Silver"
]
},
"ProductCategory": {
"S": "Bike"
},
"InStock": {
"BOOL": true
},
"QuantityOnHand": {
"N": "3"
},
"RelatedItems": {
"NS": [
"801",
"822",
"979"
]
},
"Pictures": {
"L": [
{
"M": {
"FrontView": {
"S": "http://example/products/301_front.jpg"
}
}
},
{
"M": {
"RearView": {
"S": "http://example/products/301_rear.jpg"
}
}
},
{
"M": {
"SideView": {
"S": "http://example/products/301_left_side.jpg"
}
}
}
]
},
"ProductReviews": {
"M": {
"FiveStar": {
"SS": [
"My daughter really enjoyed this bike!"
]
},
"ThreeStar": {
"SS": [
"This bike was okay, but I would have preferred it in my color.",
"Fun to ride."
]
}
}
}
}
```
## Get a Single Item by Using Expressions and the Item’s Primary Key
The following example features the `Amazon.DynamoDBv2.AmazonDynamoDBClient.GetItem` method and a set of expressions to get and then print the item that has an `Id` of `205`. Only the following attributes of the item are returned: `Id`, `Title`, `Description`, `Color`, `RelatedItems`, `Pictures`, and `ProductReviews`.
```
// using Amazon.DynamoDBv2;
// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient();
var request = new GetItemRequest
{
TableName = "ProductCatalog",
ProjectionExpression = "Id, Title, Description, Color, #ri, Pictures, #pr",
ExpressionAttributeNames = new Dictionary
{
{ "#pr", "ProductReviews" },
{ "#ri", "RelatedItems" }
},
Key = new Dictionary
{
{ "Id", new AttributeValue { N = "205" } }
},
};
var response = client.GetItem(request);
// PrintItem() is a custom function.
PrintItem(response.Item);
```
In the preceding example, the `ProjectionExpression` property specifies the attributes to be returned. The `ExpressionAttributeNames` property specifies the placeholder `#pr` to represent the `ProductReviews` attribute and the placeholder `#ri` to represent the `RelatedItems` attribute. The call to `PrintItem` refers to a custom function as described in [Print an Item](#dynamodb-expressions-print-item).
## Get Multiple Items by Using Expressions and the Table’s Primary Key
The following example features the `Amazon.DynamoDBv2.AmazonDynamoDBClient.Query` method and a set of expressions to get and then print the item that has an `Id` of `301`, but only if the value of `Price` is greater than `150`. Only the following attributes of the item are returned: `Id`, `Title`, and all of the `ThreeStar` attributes in `ProductReviews`.
```
// using Amazon.DynamoDBv2;
// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient();
var request = new QueryRequest
{
TableName = "ProductCatalog",
KeyConditions = new Dictionary
{
{ "Id", new Condition()
{
ComparisonOperator = ComparisonOperator.EQ,
AttributeValueList = new List
{
new AttributeValue { N = "301" }
}
}
}
},
ProjectionExpression = "Id, Title, #pr.ThreeStar",
ExpressionAttributeNames = new Dictionary
{
{ "#pr", "ProductReviews" },
{ "#p", "Price" }
},
ExpressionAttributeValues = new Dictionary
{
{ ":val", new AttributeValue { N = "150" } }
},
FilterExpression = "#p > :val"
};
var response = client.Query(request);
foreach (var item in response.Items)
{
// Write out the first page of an item's attribute keys and values.
// PrintItem() is a custom function.
PrintItem(item);
Console.WriteLine("=====");
}
```
In the preceding example, the `ProjectionExpression` property specifies the attributes to be returned. The `ExpressionAttributeNames` property specifies the placeholder `#pr` to represent the `ProductReviews` attribute and the placeholder `#p` to represent the `Price` attribute. `#pr.ThreeStar` specifies to return only the `ThreeStar` attribute. The `ExpressionAttributeValues` property specifies the placeholder `:val` to represent the value `150`. The `FilterExpression` property specifies that `#p` (`Price`) must be greater than `:val` (`150`). The call to `PrintItem` refers to a custom function as described in [Print an Item](#dynamodb-expressions-print-item).
## Get Multiple Items by Using Expressions and Other Item Attributes
The following example features the `Amazon.DynamoDBv2.AmazonDynamoDBClient.Scan` method and a set of expressions to get and then print all items that have a `ProductCategory` of `Bike`. Only the following attributes of the item are returned: `Id`, `Title`, and all of the attributes in `ProductReviews`.
```
// using Amazon.DynamoDBv2;
// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient();
var request = new ScanRequest
{
TableName = "ProductCatalog",
ProjectionExpression = "Id, Title, #pr",
ExpressionAttributeValues = new Dictionary
{
{ ":catg", new AttributeValue { S = "Bike" } }
},
ExpressionAttributeNames = new Dictionary
{
{ "#pr", "ProductReviews" },
{ "#pc", "ProductCategory" }
},
FilterExpression = "#pc = :catg",
};
var response = client.Scan(request);
foreach (var item in response.Items)
{
// Write out the first page/scan of an item's attribute keys and values.
// PrintItem() is a custom function.
PrintItem(item);
Console.WriteLine("=====");
}
```
In the preceding example, the `ProjectionExpression` property specifies the attributes to be returned. The `ExpressionAttributeNames` property specifies the placeholder `#pr` to represent the `ProductReviews` attribute and the placeholder `#pc` to represent the `ProductCategory` attribute. The `ExpressionAttributeValues` property specifies the placeholder `:catg` to represent the value `Bike`. The `FilterExpression` property specifies that `#pc` (`ProductCategory`) must be equal to `:catg` (`Bike`). The call to `PrintItem` refers to a custom function as described in [Print an Item](#dynamodb-expressions-print-item).
## Print an Item
The following example shows how to print an item’s attributes and values. This example is used in the preceding examples that show how to [Get a Single Item by Using Expressions and the Item’s Primary Key](#dynamodb-expressions-get-item), [Get Multiple Items by Using Expressions and the Table’s Primary Key](#dynamodb-expressions-query), and [Get Multiple Items by Using Expressions and Other Item Attributes](#dynamodb-expressions-scan).
```
// using Amazon.DynamoDBv2.Model;
// Writes out an item's attribute keys and values.
public static void PrintItem(Dictionary attrs)
{
foreach (KeyValuePair kvp in attrs)
{
Console.Write(kvp.Key + " = ");
PrintValue(kvp.Value);
}
}
// Writes out just an attribute's value.
public static void PrintValue(AttributeValue value)
{
// Binary attribute value.
if (value.B != null)
{
Console.Write("Binary data");
}
// Binary set attribute value.
else if (value.BS.Count > 0)
{
foreach (var bValue in value.BS)
{
Console.Write("\n Binary data");
}
}
// List attribute value.
else if (value.L.Count > 0)
{
foreach (AttributeValue attr in value.L)
{
PrintValue(attr);
}
}
// Map attribute value.
else if (value.M.Count > 0)
{
Console.Write("\n");
PrintItem(value.M);
}
// Number attribute value.
else if (value.N != null)
{
Console.Write(value.N);
}
// Number set attribute value.
else if (value.NS.Count > 0)
{
Console.Write("{0}", string.Join("\n", value.NS.ToArray()));
}
// Null attribute value.
else if (value.NULL)
{
Console.Write("Null");
}
// String attribute value.
else if (value.S != null)
{
Console.Write(value.S);
}
// String set attribute value.
else if (value.SS.Count > 0)
{
Console.Write("{0}", string.Join("\n", value.SS.ToArray()));
}
// Otherwise, boolean value.
else
{
Console.Write(value.BOOL);
}
Console.Write("\n");
}
```
In the preceding example, each attribute value has several data-type-specific properties that can be evaluated to determine the correct format to print the attribute. These properties include `B`, `BOOL`, `BS`, `L`, `M`, `N`, `NS`, `NULL`, `S`, and `SS`, which correspond to those in the [JSON Data Format](DataFormat.html). For properties such as `B`, `N`, `NULL`, and `S`, if the corresponding property is not `null`, then the attribute is of the corresponding non-`null` data type. For properties such as `BS`, `L`, `M`, `NS`, and `SS`, if `Count` is greater than zero, then the attribute is of the corresponding non-zero-value data type. If all of the attribute’s data-type-specific properties are either `null` or the `Count` equals zero, then the attribute corresponds to the `BOOL` data type.
## Create or Replace an Item by Using Expressions
The following example features the `Amazon.DynamoDBv2.AmazonDynamoDBClient.PutItem` method and a set of expressions to update the item that has a `Title` of `18-Bicycle 301`. If the item doesn’t already exist, a new item is added.
```
// using Amazon.DynamoDBv2;
// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient();
var request = new PutItemRequest
{
TableName = "ProductCatalog",
ExpressionAttributeNames = new Dictionary
{
{ "#title", "Title" }
},
ExpressionAttributeValues = new Dictionary
{
{ ":product", new AttributeValue { S = "18-Bicycle 301" } }
},
ConditionExpression = "#title = :product",
// CreateItemData() is a custom function.
Item = CreateItemData()
};
client.PutItem(request);
```
In the preceding example, the `ExpressionAttributeNames` property specifies the placeholder `#title` to represent the `Title` attribute. The `ExpressionAttributeValues` property specifies the placeholder `:product` to represent the value `18-Bicycle 301`. The `ConditionExpression` property specifies that `#title` (`Title`) must be equal to `:product` (`18-Bicycle 301`). The call to `CreateItemData` refers to the following custom function:
```
// using Amazon.DynamoDBv2.Model;
// Provides a sample item that can be added to a table.
public static Dictionary CreateItemData()
{
var itemData = new Dictionary
{
{ "Id", new AttributeValue { N = "301" } },
{ "Title", new AttributeValue { S = "18\" Girl's Bike" } },
{ "BicycleType", new AttributeValue { S = "Road" } },
{ "Brand" , new AttributeValue { S = "Brand-Company C" } },
{ "Color", new AttributeValue { SS = new List{ "Blue", "Silver" } } },
{ "Description", new AttributeValue { S = "301 description" } },
{ "Gender", new AttributeValue { S = "F" } },
{ "InStock", new AttributeValue { BOOL = true } },
{ "Pictures", new AttributeValue { L = new List{
{ new AttributeValue { M = new Dictionary{
{ "FrontView", new AttributeValue { S = "http://example/products/301_front.jpg" } } } } },
{ new AttributeValue { M = new Dictionary{
{ "RearView", new AttributeValue {S = "http://example/products/301_rear.jpg" } } } } },
{ new AttributeValue { M = new Dictionary{
{ "SideView", new AttributeValue { S = "http://example/products/301_left_side.jpg" } } } } }
} } },
{ "Price", new AttributeValue { N = "185" } },
{ "ProductCategory", new AttributeValue { S = "Bike" } },
{ "ProductReviews", new AttributeValue { M = new Dictionary{
{ "FiveStar", new AttributeValue { SS = new List{
"My daughter really enjoyed this bike!" } } },
{ "OneStar", new AttributeValue { SS = new List{
"Fun to ride.",
"This bike was okay, but I would have preferred it in my color." } } }
} } },
{ "QuantityOnHand", new AttributeValue { N = "3" } },
{ "RelatedItems", new AttributeValue { NS = new List{ "979", "822", "801" } } }
};
return itemData;
}
```
In the preceding example, an example item with sample data is returned to the caller. A series of attributes and corresponding values are constructed, using data types such as `BOOL`, `L`, `M`, `N`, `NS`, `S`, and `SS`, which correspond to those in the [JSON Data Format](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DataFormat.html).
## Update an Item by Using Expressions
The following example features the `Amazon.DynamoDBv2.AmazonDynamoDBClient.UpdateItem` method and a set of expressions to change the `Title` to `18" Girl's Bike` for the item with `Id` of `301`.
```
// using Amazon.DynamoDBv2;
// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient();
var request = new UpdateItemRequest
{
TableName = "ProductCatalog",
Key = new Dictionary
{
{ "Id", new AttributeValue { N = "301" } }
},
ExpressionAttributeNames = new Dictionary
{
{ "#title", "Title" }
},
ExpressionAttributeValues = new Dictionary
{
{ ":newproduct", new AttributeValue { S = "18\" Girl's Bike" } }
},
UpdateExpression = "SET #title = :newproduct"
};
client.UpdateItem(request);
```
In the preceding example, the `ExpressionAttributeNames` property specifies the placeholder `#title` to represent the `Title` attribute. The `ExpressionAttributeValues` property specifies the placeholder `:newproduct` to represent the value `18" Girl's Bike`. The `UpdateExpression` property specifies to change `#title` (`Title`) to `:newproduct` (`18" Girl's Bike`).
## Delete an Item by Using Expressions
The following example features the `Amazon.DynamoDBv2.AmazonDynamoDBClient.DeleteItem` method and a set of expressions to delete the item with `Id` of `301`, but only if the item’s `Title` is `18-Bicycle 301`.
```
// using Amazon.DynamoDBv2;
// using Amazon.DynamoDBv2.Model;
var client = new AmazonDynamoDBClient();
var request = new DeleteItemRequest
{
TableName = "ProductCatalog",
Key = new Dictionary
{
{ "Id", new AttributeValue { N = "301" } }
},
ExpressionAttributeNames = new Dictionary
{
{ "#title", "Title" }
},
ExpressionAttributeValues = new Dictionary
{
{ ":product", new AttributeValue { S = "18-Bicycle 301" } }
},
ConditionExpression = "#title = :product"
};
client.DeleteItem(request);
```
In the preceding example, the `ExpressionAttributeNames` property specifies the placeholder `#title` to represent the `Title` attribute. The `ExpressionAttributeValues` property specifies the placeholder `:product` to represent the value `18-Bicycle 301`. The `ConditionExpression` property specifies that `#title` (`Title`) must equal `:product` (`18-Bicycle 301`).
## More Info
For more information and code examples, see:
+ [DynamoDB Series - Expressions](http://blogs.aws.amazon.com/net/post/TxZQM7VA9AUZ9L/DynamoDB-Series-Expressions)
+ [Accessing Item Attributes with Projection Expressions](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.AccessingItemAttributes.html)
+ [Using Placeholders for Attribute Names and Values](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ExpressionPlaceholders.html)
+ [Specifying Conditions with Condition Expressions](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.SpecifyingConditions.html)
+ [Modifying Items and Attributes with Update Expressions](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html)
+ [Working with Items Using the AWS SDK for .NET Low-Level API](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LowLevelDotNetItemCRUD.html)
+ [Querying Tables Using the AWS SDK for .NET Low-Level API](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LowLevelDotNetQuerying.html)
+ [Scanning Tables Using the AWS SDK for .NET Low-Level API](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LowLevelDotNetScanning.html)
+ [Working with Local Secondary Indexes Using the AWS SDK for .NET Low-Level API](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LSILowLevelDotNet.html)
+ [Working with Global Secondary Indexes Using the AWS SDK for .NET Low-Level API](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSILowLevelDotNet.html)
# JSON support in Amazon DynamoDB
**Note**
The information in this topic is specific to projects based on .NET Framework and the AWS SDK for .NET version 3.3 and earlier.
The AWS SDK for .NET supports JSON data when working with Amazon DynamoDB. This enables you to more easily get JSON-formatted data from, and insert JSON documents into, DynamoDB tables.
**Topics**
+ [Get Data from a DynamoDB Table in JSON Format](#dynamodb-json-get-table-data)
+ [Insert JSON Format Data into a DynamoDB Table](#dynamodb-json-insert-table-data)
+ [DynamoDB Data Type Conversions to JSON](#dynamodb-json-datatypes)
+ [More Info](#dynamodb-json-more-info)
## Get Data from a DynamoDB Table in JSON Format
The following example shows how to get data from a DynamoDB table in JSON format:
```
// using Amazon.DynamoDBv2;
// using Amazon.DynamoDBv2.DocumentModel;
var client = new AmazonDynamoDBClient();
var table = Table.LoadTable(client, "AnimalsInventory");
var item = table.GetItem(3, "Horse");
var jsonText = item.ToJson();
Console.Write(jsonText);
// Output:
// {"Name":"Shadow","Type":"Horse","Id":3}
var jsonPrettyText = item.ToJsonPretty();
Console.WriteLine(jsonPrettyText);
// Output:
// {
// "Name" : "Shadow",
// "Type" : "Horse",
// "Id" : 3
// }
```
In the preceding example, the `ToJson` method of the `Document` class converts an item from the table into a JSON-formatted string. The item is retrieved through the `GetItem` method of the `Table` class. To determine the item to get, in this example, the `GetItem` method uses the hash-and-range primary key of the target item. To determine the table to get the item from, the `LoadTable` method of the `Table` class uses an instance of the `AmazonDynamoDBClient` class and the name of the target table in DynamoDB.
## Insert JSON Format Data into a DynamoDB Table
The following example shows how to use JSON format to insert an item into a DynamoDB table:
```
// using Amazon.DynamoDBv2;
// using Amazon.DynamoDBv2.DocumentModel;
var client = new AmazonDynamoDBClient();
var table = Table.LoadTable(client, "AnimalsInventory");
var jsonText = "{\"Id\":6,\"Type\":\"Bird\",\"Name\":\"Tweety\"}";
var item = Document.FromJson(jsonText);
table.PutItem(item);
```
In the preceding example, the `FromJson` method of the `Document` class converts a JSON-formatted string into an item. The item is inserted into the table through the `PutItem` method of the `Table` class, which uses the instance of the `Document` class that contains the item. To determine the table to insert the item into, the `LoadTable` method of the `Table` class is called, specifying an instance of the `AmazonDynamoDBClient` class and the name of the target table in DynamoDB.
## DynamoDB Data Type Conversions to JSON
Whenever you call the `ToJson` method of the `Document` class, and then on the resulting JSON data you call the `FromJson` method to convert the JSON data back into an instance of a `Document` class, some DynamoDB data types will not be converted as expected. Specifically:
+ DynamoDB sets (the `SS`, `NS`, and `BS` types) will be converted to JSON arrays.
+ DynamoDB binary scalars and sets (the `B` and `BS` types) will be converted to base64-encoded JSON strings or lists of strings.
In this scenario, you must call the `DecodeBase64Attributes` method of the `Document` class to replace the base64-encoded JSON data with the correct binary representation. The following example replaces a base64-encoded binary scalar item attribute in an instance of a `Document` class, named `Picture`, with the correct binary representation. This example also does the same for a base64-encoded binary set item attribute in the same instance of the `Document` class, named `RelatedPictures`:
```
item.DecodeBase64Attributes("Picture", "RelatedPictures");
```
## More Info
For more information and examples of programming JSON with DynamoDB with the AWS SDK for .NET, see:
+ [DynamoDB JSON Support](https://aws.amazon.com/blogs/developer/dynamodb-json-support/)
+ [Amazon DynamoDB Update - JSON, Expanded Free Tier, Flexible Scaling, Larger Items](https://aws.amazon.com/blogs/aws/dynamodb-update-json-and-more/)
# Working with Amazon EC2
The AWS SDK for .NET supports [Amazon EC2](https://docs.aws.amazon.com/ec2/), which is a web service that provides resizable computing capacity. You use this computing capacity to build and host your software systems.
## APIs
The AWS SDK for .NET provides APIs for Amazon EC2 clients. The APIs enable you to work with EC2 features such as security groups and key pairs. The APIs also enable you to control Amazon EC2 instances. This section contains a small number of examples that show you the patterns you can follow when working with these APIs. To view the full set of APIs, see the [AWS SDK for .NET API Reference](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/) (and scroll to "Amazon.EC2").
The Amazon EC2 APIs are provided by the [AWSSDK.EC2](https://www.nuget.org/packages/AWSSDK.EC2) NuGet package.
## Prerequisites
Before you begin, be sure you have [set up your environment and project](net-dg-config.md). Also review the information in [SDK features](net-dg-sdk-features.md).
## About the examples
The examples in this section show you how to work with Amazon EC2 clients and manage Amazon EC2 instances.
The [EC2 Spot Instance tutorial](how-to-spot-instances.md) shows you how to request Amazon EC2 Spot Instances. Spot Instances enable you to access unused EC2 capacity for less than the On-Demand price.
**Topics**
+ [APIs](#w2aac19c15c17b5)
+ [Prerequisites](#w2aac19c15c17b7)
+ [About the examples](#ec2-apis-intro-about)
+ [Security groups](security-groups.md)
+ [Key pairs](key-pairs.md)
+ [Regions and Availability Zones](using-regions-and-availability-zones.md)
+ [EC2 instances](how-to-ec2.md)
+ [Spot Instance tutorial](how-to-spot-instances.md)
# Working with security groups in Amazon EC2
In Amazon EC2, a *security group* acts as a virtual firewall that controls the network traffic for one or more EC2 instances. By default, EC2 associates your instances with a security group that allows no inbound traffic. You can create a security group that allows your EC2 instances to accept certain traffic. For example, if you need to connect to an EC2 Windows instance, you must configure the security group to allow RDP traffic.
To read more about security groups see [Amazon EC2 security groups](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-security-groups.html) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/).
**Warning**
EC2-Classic was retired on August 15, 2022. We recommend that you migrate from EC2-Classic to a VPC. For more information, see the blog post [EC2-Classic Networking is Retiring – Here's How to Prepare](https://aws.amazon.com/blogs/aws/ec2-classic-is-retiring-heres-how-to-prepare/).
For information about the APIs and prerequisites, see the parent section ([Working with Amazon EC2](ec2-apis-intro.md)).
**Topics**
+ [Enumerating security groups](enumerate-security-groups.md)
+ [Creating security groups](creating-security-group.md)
+ [Updating security groups](authorize-ingress.md)
# Enumerating security groups
This example shows you how to use the AWS SDK for .NET to enumerate security groups. If you supply an [Amazon Virtual Private Cloud](https://docs.aws.amazon.com/vpc/latest/userguide/) ID, the application enumerates the security groups for that particular VPC. Otherwise, the application simply displays a list of all available security groups.
The following sections provide snippets of this example. The [complete code for the example](#enum-sec-groups-complete-code) is shown after that, and can be built and run as is.
**Topics**
+ [Enumerate security groups](#enum-sec-groups-enum)
+ [Complete code](#enum-sec-groups-complete-code)
+ [Additional considerations](#enum-sec-groups-additional)
## Enumerate security groups
The following snippet enumerates your security groups. It enumerates all groups or the groups for a particular VPC if one is given.
The example [at the end of this topic](#enum-sec-groups-complete-code) shows this snippet in use.
```
//
// Method to enumerate the security groups
private static async Task EnumerateGroups(IAmazonEC2 ec2Client, string vpcID)
{
// A request object, in case we need it.
var request = new DescribeSecurityGroupsRequest();
// Put together the properties, if needed
if(!string.IsNullOrEmpty(vpcID))
{
// We have a VPC ID. Find the security groups for just that VPC.
Console.WriteLine($"\nGetting security groups for VPC {vpcID}...\n");
request.Filters.Add(new Filter
{
Name = "vpc-id",
Values = new List() { vpcID }
});
}
// Get the list of security groups
DescribeSecurityGroupsResponse response =
await ec2Client.DescribeSecurityGroupsAsync(request);
// Display the list of security groups.
foreach (SecurityGroup item in response.SecurityGroups)
{
Console.WriteLine("Security group: " + item.GroupId);
Console.WriteLine("\tGroupId: " + item.GroupId);
Console.WriteLine("\tGroupName: " + item.GroupName);
Console.WriteLine("\tVpcId: " + item.VpcId);
Console.WriteLine();
}
}
```
## Complete code
This section shows relevant references and the complete code for this example.
### SDK references
NuGet packages:
+ [AWSSDK.EC2](https://www.nuget.org/packages/AWSSDK.EC2)
Programming elements:
+ Namespace [Amazon.EC2](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2.html)
Class [AmazonEC2Client](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TEC2Client.html)
+ Namespace [Amazon.EC2.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2Model.html)
Class [DescribeSecurityGroupsRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TDescribeSecurityGroupsRequest.html)
Class [DescribeSecurityGroupsResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TDescribeSecurityGroupsResponse.html)
Class [Filter](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TFilter.html)
Class [SecurityGroup](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TSecurityGroup.html)
### The Code
```
using System;
using System.Threading.Tasks;
using System.Collections.Generic;
using Amazon.EC2;
using Amazon.EC2.Model;
namespace EC2EnumerateSecGroups
{
class Program
{
static async Task Main(string[] args)
{
// Parse the command line
string vpcID = string.Empty;
if(args.Length == 0)
{
Console.WriteLine("\nEC2EnumerateSecGroups [vpc_id]");
Console.WriteLine(" vpc_id - The ID of the VPC for which you want to see security groups.");
Console.WriteLine("\nSince you specified no arguments, showing all available security groups.");
}
else
{
vpcID = args[0];
}
if(vpcID.StartsWith("vpc-") || string.IsNullOrEmpty(vpcID))
{
// Create an EC2 client object
var ec2Client = new AmazonEC2Client();
// Enumerate the security groups
await EnumerateGroups(ec2Client, vpcID);
}
else
{
Console.WriteLine("Could not find a valid VPC ID in the command-line arguments:");
Console.WriteLine($"{args[0]}");
}
}
//
// Method to enumerate the security groups
private static async Task EnumerateGroups(IAmazonEC2 ec2Client, string vpcID)
{
// A request object, in case we need it.
var request = new DescribeSecurityGroupsRequest();
// Put together the properties, if needed
if(!string.IsNullOrEmpty(vpcID))
{
// We have a VPC ID. Find the security groups for just that VPC.
Console.WriteLine($"\nGetting security groups for VPC {vpcID}...\n");
request.Filters.Add(new Filter
{
Name = "vpc-id",
Values = new List() { vpcID }
});
}
// Get the list of security groups
DescribeSecurityGroupsResponse response =
await ec2Client.DescribeSecurityGroupsAsync(request);
// Display the list of security groups.
foreach (SecurityGroup item in response.SecurityGroups)
{
Console.WriteLine("Security group: " + item.GroupId);
Console.WriteLine("\tGroupId: " + item.GroupId);
Console.WriteLine("\tGroupName: " + item.GroupName);
Console.WriteLine("\tVpcId: " + item.VpcId);
Console.WriteLine();
}
}
}
}
```
## Additional considerations
+ Notice for the VPC case that the filter is constructed with the `Name` part of the name-value pair set to "vpc-id". This name comes from the description for the `Filters` property of the [DescribeSecurityGroupsRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TDescribeSecurityGroupsRequest.html) class.
+ To get the complete list of your security groups, you can also use [ DescribeSecurityGroupsAsync with no parameters](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/MEC2DescribeSecurityGroupsAsyncCancellationToken.html).
+ You can verify the results by checking the list of security groups in the [Amazon EC2 console](https://console.aws.amazon.com/ec2/v2/home#SecurityGroups).
# Creating security groups
This example shows you how to use the AWS SDK for .NET to create a security group. You can provide the ID of an existing VPC to create a security group for EC2 in a VPC. If you don't supply such an ID, the new security group will be for EC2-Classic if your AWS account supports this.
If you don't supply a VPC ID and your AWS account doesn't support EC2-Classic, the new security group will belong to the default VPC of your account.
**Warning**
EC2-Classic was retired on August 15, 2022. We recommend that you migrate from EC2-Classic to a VPC. For more information, see the blog post [EC2-Classic Networking is Retiring – Here's How to Prepare](https://aws.amazon.com/blogs/aws/ec2-classic-is-retiring-heres-how-to-prepare/).
The following sections provide snippets of this example. The [complete code for the example](#create-sec-groups-complete-code) is shown after that, and can be built and run as is.
**Topics**
+ [Find existing security groups](#create-sec-groups-find)
+ [Create a security group](#create-sec-groups-enum)
+ [Complete code](#create-sec-groups-complete-code)
## Find existing security groups
The following snippet searches for existing security groups with the given name in the given VPC.
The example [at the end of this topic](#create-sec-groups-complete-code) shows this snippet in use.
```
//
// Method to determine if a security group with the specified name
// already exists in the VPC
private static async Task> FindSecurityGroups(
IAmazonEC2 ec2Client, string groupName, string vpcID)
{
var request = new DescribeSecurityGroupsRequest();
request.Filters.Add(new Filter{
Name = "group-name",
Values = new List() { groupName }
});
if(!string.IsNullOrEmpty(vpcID))
request.Filters.Add(new Filter{
Name = "vpc-id",
Values = new List() { vpcID }
});
var response = await ec2Client.DescribeSecurityGroupsAsync(request);
return response.SecurityGroups;
}
```
## Create a security group
The following snippet creates a new security group if a group with that name doesn't exist in the given VPC. If no VPC is given and one or more groups with that name exist, the snippet simply returns the list of groups.
The example [at the end of this topic](#create-sec-groups-complete-code) shows this snippet in use.
```
//
// Method to create a new security group (either EC2-Classic or EC2-VPC)
// If vpcID is empty, the security group will be for EC2-Classic
private static async Task> CreateSecurityGroup(
IAmazonEC2 ec2Client, string groupName, string vpcID)
{
// See if one or more security groups with that name
// already exist in the given VPC. If so, return the list of them.
var securityGroups = await FindSecurityGroups(ec2Client, groupName, vpcID);
if (securityGroups.Count > 0)
{
Console.WriteLine(
$"\nOne or more security groups with name {groupName} already exist.\n");
return securityGroups;
}
// If the security group doesn't already exists, create it.
var createRequest = new CreateSecurityGroupRequest{
GroupName = groupName
};
if(string.IsNullOrEmpty(vpcID))
{
createRequest.Description = "My .NET example security group for EC2-Classic";
}
else
{
createRequest.VpcId = vpcID;
createRequest.Description = "My .NET example security group for EC2-VPC";
}
CreateSecurityGroupResponse createResponse =
await ec2Client.CreateSecurityGroupAsync(createRequest);
// Return the new security group
DescribeSecurityGroupsResponse describeResponse =
await ec2Client.DescribeSecurityGroupsAsync(new DescribeSecurityGroupsRequest{
GroupIds = new List() { createResponse.GroupId }
});
return describeResponse.SecurityGroups;
}
```
## Complete code
This section shows relevant references and the complete code for this example.
### SDK references
NuGet packages:
+ [AWSSDK.EC2](https://www.nuget.org/packages/AWSSDK.EC2)
Programming elements:
+ Namespace [Amazon.EC2](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2.html)
Class [AmazonEC2Client](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TEC2Client.html)
+ Namespace [Amazon.EC2.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2Model.html)
Class [CreateSecurityGroupRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TCreateSecurityGroupRequest.html)
Class [CreateSecurityGroupResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TCreateSecurityGroupResponse.html)
Class [DescribeSecurityGroupsRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TDescribeSecurityGroupsRequest.html)
Class [DescribeSecurityGroupsResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TDescribeSecurityGroupsResponse.html)
Class [Filter ](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TFilter.html)
Class [SecurityGroup](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TSecurityGroup.html)
### The code
```
using System;
using System.Threading.Tasks;
using System.Collections.Generic;
using Amazon.EC2;
using Amazon.EC2.Model;
namespace EC2CreateSecGroup
{
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class to create a security group
class Program
{
private const int MaxArgs = 2;
static async Task Main(string[] args)
{
// Parse the command line and show help if necessary
var parsedArgs = CommandLine.Parse(args);
if(parsedArgs.Count == 0)
{
PrintHelp();
return;
}
if(parsedArgs.Count > MaxArgs)
CommandLine.ErrorExit("\nThe number of command-line arguments is incorrect." +
"\nRun the command with no arguments to see help.");
// Get the application arguments from the parsed list
var groupName = CommandLine.GetArgument(parsedArgs, null, "-g", "--group-name");
var vpcID = CommandLine.GetArgument(parsedArgs, null, "-v", "--vpc-id");
if(string.IsNullOrEmpty(groupName))
CommandLine.ErrorExit("\nYou must supply a name for the new group." +
"\nRun the command with no arguments to see help.");
if(!string.IsNullOrEmpty(vpcID) && !vpcID.StartsWith("vpc-"))
CommandLine.ErrorExit($"\nNot a valid VPC ID: {vpcID}");
// groupName has a value and vpcID either has a value or is null (which is fine)
// Create the new security group and display information about it
var securityGroups =
await CreateSecurityGroup(new AmazonEC2Client(), groupName, vpcID);
Console.WriteLine("Information about the security group(s):");
foreach(var group in securityGroups)
{
Console.WriteLine($"\nGroupName: {group.GroupName}");
Console.WriteLine($"GroupId: {group.GroupId}");
Console.WriteLine($"Description: {group.Description}");
Console.WriteLine($"VpcId (if any): {group.VpcId}");
}
}
//
// Method to create a new security group (either EC2-Classic or EC2-VPC)
// If vpcID is empty, the security group will be for EC2-Classic
private static async Task> CreateSecurityGroup(
IAmazonEC2 ec2Client, string groupName, string vpcID)
{
// See if one or more security groups with that name
// already exist in the given VPC. If so, return the list of them.
var securityGroups = await FindSecurityGroups(ec2Client, groupName, vpcID);
if (securityGroups.Count > 0)
{
Console.WriteLine(
$"\nOne or more security groups with name {groupName} already exist.\n");
return securityGroups;
}
// If the security group doesn't already exists, create it.
var createRequest = new CreateSecurityGroupRequest{
GroupName = groupName
};
if(string.IsNullOrEmpty(vpcID))
{
createRequest.Description = "Security group for .NET code example (no VPC specified)";
}
else
{
createRequest.VpcId = vpcID;
createRequest.Description = "Security group for .NET code example (VPC: " + vpcID + ")";
}
CreateSecurityGroupResponse createResponse =
await ec2Client.CreateSecurityGroupAsync(createRequest);
// Return the new security group
DescribeSecurityGroupsResponse describeResponse =
await ec2Client.DescribeSecurityGroupsAsync(new DescribeSecurityGroupsRequest{
GroupIds = new List() { createResponse.GroupId }
});
return describeResponse.SecurityGroups;
}
//
// Method to determine if a security group with the specified name
// already exists in the VPC
private static async Task> FindSecurityGroups(
IAmazonEC2 ec2Client, string groupName, string vpcID)
{
var request = new DescribeSecurityGroupsRequest();
request.Filters.Add(new Filter{
Name = "group-name",
Values = new List() { groupName }
});
if(!string.IsNullOrEmpty(vpcID))
request.Filters.Add(new Filter{
Name = "vpc-id",
Values = new List() { vpcID }
});
var response = await ec2Client.DescribeSecurityGroupsAsync(request);
return response.SecurityGroups;
}
//
// Command-line help
private static void PrintHelp()
{
Console.WriteLine(
"\nUsage: EC2CreateSecGroup -g [-v ]" +
"\n -g, --group-name: The name you would like the new security group to have." +
"\n -v, --vpc-id: The ID of a VPC to which the new security group will belong." +
"\n If vpc-id isn't present, the security group will be" +
"\n for EC2-Classic (if your AWS account supports this)" +
"\n or will use the default VCP for EC2-VPC.");
}
}
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class that represents a command line on the console or terminal.
// (This is the same for all examples. When you have seen it once, you can ignore it.)
static class CommandLine
{
//
// Method to parse a command line of the form: "--key value" or "-k value".
//
// Parameters:
// - args: The command-line arguments passed into the application by the system.
//
// Returns:
// A Dictionary with string Keys and Values.
//
// If a key is found without a matching value, Dictionary.Value is set to the key
// (including the dashes).
// If a value is found without a matching key, Dictionary.Key is set to "--NoKeyN",
// where "N" represents sequential numbers.
public static Dictionary Parse(string[] args)
{
var parsedArgs = new Dictionary();
int i = 0, n = 0;
while(i < args.Length)
{
// If the first argument in this iteration starts with a dash it's an option.
if(args[i].StartsWith("-"))
{
var key = args[i++];
var value = key;
// Check to see if there's a value that goes with this option?
if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++];
parsedArgs.Add(key, value);
}
// If the first argument in this iteration doesn't start with a dash, it's a value
else
{
parsedArgs.Add("--NoKey" + n.ToString(), args[i++]);
n++;
}
}
return parsedArgs;
}
//
// Method to get an argument from the parsed command-line arguments
//
// Parameters:
// - parsedArgs: The Dictionary object returned from the Parse() method (shown above).
// - defaultValue: The default string to return if the specified key isn't in parsedArgs.
// - keys: An array of keys to look for in parsedArgs.
public static string GetArgument(
Dictionary parsedArgs, string defaultReturn, params string[] keys)
{
string retval = null;
foreach(var key in keys)
if(parsedArgs.TryGetValue(key, out retval)) break;
return retval ?? defaultReturn;
}
//
// Method to exit the application with an error.
public static void ErrorExit(string msg, int code=1)
{
Console.WriteLine("\nError");
Console.WriteLine(msg);
Environment.Exit(code);
}
}
}
```
# Updating security groups
This example shows you how to use the AWS SDK for .NET to add a rule to a security group. In particular, the example adds a rule to allow inbound traffic on a given TCP port, which can be used, for example, for remote connections to an EC2 instance. The application takes the ID of an existing security group, an IP address (or address range) in CIDR format, and optionally a TCP port number. It then adds an inbound rule to the given security group.
**Note**
To use this example, you need an IP address (or address range) in CIDR format. See **Additional considerations** at this end of this topic for methods to obtain the IP address of your local computer.
The following sections provide snippets of this example. The [complete code for the example](#authorize-ingress-complete-code) is shown after that, and can be built and run as is.
**Topics**
+ [Add an inbound rule](#authorize-ingress-add-rule)
+ [Complete code](#authorize-ingress-complete-code)
+ [Additional considerations](#authorize-ingress-additional)
## Add an inbound rule
The following snippet adds an inbound rule to a security group for a particular IP address (or range) and TCP port.
The example [at the end of this topic](#authorize-ingress-complete-code) shows this snippet in use.
```
//
// Method that adds a TCP ingress rule to a security group
private static async Task AddIngressRule(
IAmazonEC2 eC2Client, string groupID, string ipAddress, int port)
{
// Create an object to hold the request information for the rule.
// It uses an IpPermission object to hold the IP information for the rule.
var ingressRequest = new AuthorizeSecurityGroupIngressRequest{
GroupId = groupID};
ingressRequest.IpPermissions.Add(new IpPermission{
IpProtocol = "tcp",
FromPort = port,
ToPort = port,
Ipv4Ranges = new List() { new IpRange { CidrIp = ipAddress } }
});
// Create the inbound rule for the security group
AuthorizeSecurityGroupIngressResponse responseIngress =
await eC2Client.AuthorizeSecurityGroupIngressAsync(ingressRequest);
Console.WriteLine($"\nNew RDP rule was written in {groupID} for {ipAddress}.");
Console.WriteLine($"Result: {responseIngress.HttpStatusCode}");
}
```
## Complete code
This section shows relevant references and the complete code for this example.
### SDK references
NuGet packages:
+ [AWSSDK.EC2](https://www.nuget.org/packages/AWSSDK.EC2)
Programming elements:
+ Namespace [Amazon.EC2](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2.html)
Class [AmazonEC2Client](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TEC2Client.html)
+ Namespace [Amazon.EC2.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2Model.html)
Class [AuthorizeSecurityGroupIngressRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TAuthorizeSecurityGroupIngressRequest.html)
Class [AuthorizeSecurityGroupIngressResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TAuthorizeSecurityGroupIngressResponse.html)
Class [IpPermission](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TIpPermission.html)
Class [IpRange](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TIpRange.html)
### The code
```
using System;
using System.Threading.Tasks;
using System.Collections.Generic;
using Amazon.EC2;
using Amazon.EC2.Model;
namespace EC2AddRuleForRDP
{
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class to add a rule that allows inbound traffic on TCP a port
class Program
{
private const int DefaultPort = 3389;
static async Task Main(string[] args)
{
// Parse the command line and show help if necessary
var parsedArgs = CommandLine.Parse(args);
if(parsedArgs.Count == 0)
{
PrintHelp();
return;
}
// Get the application arguments from the parsed list
var groupID = CommandLine.GetArgument(parsedArgs, null, "-g", "--group-id");
var ipAddress = CommandLine.GetArgument(parsedArgs, null, "-i", "--ip-address");
var portStr = CommandLine.GetArgument(parsedArgs, DefaultPort.ToString(), "-p", "--port");
if(string.IsNullOrEmpty(ipAddress))
CommandLine.ErrorExit("\nYou must supply an IP address in CIDR format.");
if(string.IsNullOrEmpty(groupID) || !groupID.StartsWith("sg-"))
CommandLine.ErrorExit("\nThe ID for a security group is missing or incorrect.");
if(int.Parse(portStr) == 0)
CommandLine.ErrorExit($"\nThe given TCP port number, {portStr}, isn't allowed.");
// Add a rule to the given security group that allows
// inbound traffic on a TCP port
await AddIngressRule(
new AmazonEC2Client(), groupID, ipAddress, int.Parse(portStr));
}
//
// Method that adds a TCP ingress rule to a security group
private static async Task AddIngressRule(
IAmazonEC2 eC2Client, string groupID, string ipAddress, int port)
{
// Create an object to hold the request information for the rule.
// It uses an IpPermission object to hold the IP information for the rule.
var ingressRequest = new AuthorizeSecurityGroupIngressRequest{
GroupId = groupID};
ingressRequest.IpPermissions.Add(new IpPermission{
IpProtocol = "tcp",
FromPort = port,
ToPort = port,
Ipv4Ranges = new List() { new IpRange { CidrIp = ipAddress } }
});
// Create the inbound rule for the security group
AuthorizeSecurityGroupIngressResponse responseIngress =
await eC2Client.AuthorizeSecurityGroupIngressAsync(ingressRequest);
Console.WriteLine($"\nNew RDP rule was written in {groupID} for {ipAddress}.");
Console.WriteLine($"Result: {responseIngress.HttpStatusCode}");
}
//
// Command-line help
private static void PrintHelp()
{
Console.WriteLine(
"\nUsage: EC2AddRuleForRDP -g -i [-p ]" +
"\n -g, --group-id: The ID of the security group to which you want to add the inbound rule." +
"\n -i, --ip-address: An IP address or address range in CIDR format." +
"\n -p, --port: The TCP port number. Defaults to 3389.");
}
}
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class that represents a command line on the console or terminal.
// (This is the same for all examples. When you have seen it once, you can ignore it.)
static class CommandLine
{
//
// Method to parse a command line of the form: "--key value" or "-k value".
//
// Parameters:
// - args: The command-line arguments passed into the application by the system.
//
// Returns:
// A Dictionary with string Keys and Values.
//
// If a key is found without a matching value, Dictionary.Value is set to the key
// (including the dashes).
// If a value is found without a matching key, Dictionary.Key is set to "--NoKeyN",
// where "N" represents sequential numbers.
public static Dictionary Parse(string[] args)
{
var parsedArgs = new Dictionary();
int i = 0, n = 0;
while(i < args.Length)
{
// If the first argument in this iteration starts with a dash it's an option.
if(args[i].StartsWith("-"))
{
var key = args[i++];
var value = key;
// Check to see if there's a value that goes with this option?
if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++];
parsedArgs.Add(key, value);
}
// If the first argument in this iteration doesn't start with a dash, it's a value
else
{
parsedArgs.Add("--NoKey" + n.ToString(), args[i++]);
n++;
}
}
return parsedArgs;
}
//
// Method to get an argument from the parsed command-line arguments
//
// Parameters:
// - parsedArgs: The Dictionary object returned from the Parse() method (shown above).
// - defaultValue: The default string to return if the specified key isn't in parsedArgs.
// - keys: An array of keys to look for in parsedArgs.
public static string GetArgument(
Dictionary parsedArgs, string defaultReturn, params string[] keys)
{
string retval = null;
foreach(var key in keys)
if(parsedArgs.TryGetValue(key, out retval)) break;
return retval ?? defaultReturn;
}
//
// Method to exit the application with an error.
public static void ErrorExit(string msg, int code=1)
{
Console.WriteLine("\nError");
Console.WriteLine(msg);
Environment.Exit(code);
}
}
}
```
## Additional considerations
+ If you don't supply a port number, the application defaults to port 3389. This is the port for Windows RDP, which enables you to connect to an EC2 instance running Windows. If you're launching an EC2 instance running Linux, you can use TCP port 22 (SSH) instead.
+ Notice that the example sets `IpProtocol` to "tcp". The values for `IpProtocol` can be found in the description for the `IpProtocol` property of the [IpPermission](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TIpPermission.html) class.
+ You might want the IP address of your local computer when you use this example. The following are some of the ways in which you can obtain the address.
+ If your local computer (from which you will connect to your EC2 instance) has a static public IP address, you can use a service to get that address. One such service is [http://checkip.amazonaws.com/](http://checkip.amazonaws.com/). To read more about authorizing inbound traffic, see [Add rules to a security group](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/working-with-security-groups.html#adding-security-group-rule) and [Security group rules for different use cases](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-group-rules-reference.html) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/).
+ Another way to obtain the IP address of your local computer is to use the [Amazon EC2 console](https://console.aws.amazon.com/ec2/v2/home#SecurityGroups).
Select one of your security groups, select the **Inbound rules** tab, and choose **Edit inbound rules**. In an inbound rule, open the drop-down menu in the **Source** column and choose **My IP** to see the IP address of your local computer in CIDR format. Be sure to **Cancel** the operation.
+ You can verify the results of this example by examining the list of security groups in the [Amazon EC2 console](https://console.aws.amazon.com/ec2/v2/home#SecurityGroups).
# Working with Amazon EC2 key pairs
Amazon EC2 uses public–key cryptography to encrypt and decrypt login information. Public–key cryptography uses a public key to encrypt data, and then the recipient uses the private key to decrypt the data. The public and private keys are known as a key pair. If you want to log into an EC2 instance, you must specify a key pair when you launch it, and then provide the private key of the pair when you connect to it.
When you launch an EC2 instance, you can create a key pair for it or use one that you've already used when launching other instances. To read more about Amazon EC2 key pairs, see [Working with Amazon EC2 key pairs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/).
For information about the APIs and prerequisites, see the parent section ([Working with Amazon EC2](ec2-apis-intro.md)).
**Topics**
+ [Creating and displaying key pairs](create-save-key-pair.md)
+ [Deleting key pairs](delete-key-pairs.md)
# Creating and displaying key pairs
This example shows you how to use the AWS SDK for .NET to create a key pair. The application takes the name for the new key pair and the name of a PEM file (with a ".pem" extension). It creates the keypair, writes the private key to the PEM file, and then displays all available key pairs. If you provide no command-line arguments, the application simply displays all available key pairs.
The following sections provide snippets of this example. The [complete code for the example](#create-save-key-pair-complete-code) is shown after that, and can be built and run as is.
**Topics**
+ [Create the key pair](#create-save-key-pair-create)
+ [Display available key pairs](#create-save-key-pair-display)
+ [Complete code](#create-save-key-pair-complete-code)
+ [Additional considerations](#create-save-key-pair-additional)
## Create the key pair
The following snippet creates a key pair and then stores the private key to the given PEM file.
The example [at the end of this topic](#create-save-key-pair-complete-code) shows this snippet in use.
```
//
// Method to create a key pair and save the key material in a PEM file
private static async Task CreateKeyPair(
IAmazonEC2 ec2Client, string keyPairName, string pemFileName)
{
// Create the key pair
CreateKeyPairResponse response =
await ec2Client.CreateKeyPairAsync(new CreateKeyPairRequest{
KeyName = keyPairName
});
Console.WriteLine($"\nCreated new key pair: {response.KeyPair.KeyName}");
// Save the private key in a PEM file
using (var s = new FileStream(pemFileName, FileMode.Create))
using (var writer = new StreamWriter(s))
{
writer.WriteLine(response.KeyPair.KeyMaterial);
}
}
```
## Display available key pairs
The following snippet displays a list of the available key pairs.
The example [at the end of this topic](#create-save-key-pair-complete-code) shows this snippet in use.
```
//
// Method to show the key pairs that are available
private static async Task EnumerateKeyPairs(IAmazonEC2 ec2Client)
{
DescribeKeyPairsResponse response = await ec2Client.DescribeKeyPairsAsync();
Console.WriteLine("Available key pairs:");
foreach (KeyPairInfo item in response.KeyPairs)
Console.WriteLine($" {item.KeyName}");
}
```
## Complete code
This section shows relevant references and the complete code for this example.
### SDK references
NuGet packages:
+ [AWSSDK.EC2](https://www.nuget.org/packages/AWSSDK.EC2)
Programming elements:
+ Namespace [Amazon.EC2](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2.html)
Class [AmazonEC2Client](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TEC2Client.html)
+ Namespace [Amazon.EC2.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2Model.html)
Class [CreateKeyPairRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TCreateKeyPairRequest.html)
Class [CreateKeyPairResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TCreateKeyPairResponse.html)
Class [DescribeKeyPairsResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TDescribeKeyPairsResponse.html)
Class [KeyPairInfo](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TKeyPairInfo.html)
### The code
```
using System;
using System.Threading.Tasks;
using System.IO;
using Amazon.EC2;
using Amazon.EC2.Model;
using System.Collections.Generic;
namespace EC2CreateKeyPair
{
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class to create and store a key pair
class Program
{
static async Task Main(string[] args)
{
// Create the EC2 client
var ec2Client = new AmazonEC2Client();
// Parse the command line and show help if necessary
var parsedArgs = CommandLine.Parse(args);
if(parsedArgs.Count == 0)
{
// In the case of no command-line arguments,
// just show help and the existing key pairs
PrintHelp();
Console.WriteLine("\nNo arguments specified.");
Console.Write(
"Do you want to see a list of the existing key pairs? ((y) or n): ");
string response = Console.ReadLine();
if((string.IsNullOrEmpty(response)) || (response.ToLower() == "y"))
await EnumerateKeyPairs(ec2Client);
return;
}
// Get the application arguments from the parsed list
string keyPairName =
CommandLine.GetArgument(parsedArgs, null, "-k", "--keypair-name");
string pemFileName =
CommandLine.GetArgument(parsedArgs, null, "-p", "--pem-filename");
if(string.IsNullOrEmpty(keyPairName))
CommandLine.ErrorExit("\nNo key pair name specified." +
"\nRun the command with no arguments to see help.");
if(string.IsNullOrEmpty(pemFileName) || !pemFileName.EndsWith(".pem"))
CommandLine.ErrorExit("\nThe PEM filename is missing or incorrect." +
"\nRun the command with no arguments to see help.");
// Create the key pair
await CreateKeyPair(ec2Client, keyPairName, pemFileName);
await EnumerateKeyPairs(ec2Client);
}
//
// Method to create a key pair and save the key material in a PEM file
private static async Task CreateKeyPair(
IAmazonEC2 ec2Client, string keyPairName, string pemFileName)
{
// Create the key pair
CreateKeyPairResponse response =
await ec2Client.CreateKeyPairAsync(new CreateKeyPairRequest{
KeyName = keyPairName
});
Console.WriteLine($"\nCreated new key pair: {response.KeyPair.KeyName}");
// Save the private key in a PEM file
using (var s = new FileStream(pemFileName, FileMode.Create))
using (var writer = new StreamWriter(s))
{
writer.WriteLine(response.KeyPair.KeyMaterial);
}
}
//
// Method to show the key pairs that are available
private static async Task EnumerateKeyPairs(IAmazonEC2 ec2Client)
{
DescribeKeyPairsResponse response = await ec2Client.DescribeKeyPairsAsync();
Console.WriteLine("Available key pairs:");
foreach (KeyPairInfo item in response.KeyPairs)
Console.WriteLine($" {item.KeyName}");
}
//
// Command-line help
private static void PrintHelp()
{
Console.WriteLine(
"\nUsage: EC2CreateKeyPair -k -p " +
"\n -k, --keypair-name: The name you want to assign to the key pair." +
"\n -p, --pem-filename: The name of the PEM file to create, with a \".pem\" extension.");
}
}
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class that represents a command line on the console or terminal.
// (This is the same for all examples. When you have seen it once, you can ignore it.)
static class CommandLine
{
//
// Method to parse a command line of the form: "--key value" or "-k value".
//
// Parameters:
// - args: The command-line arguments passed into the application by the system.
//
// Returns:
// A Dictionary with string Keys and Values.
//
// If a key is found without a matching value, Dictionary.Value is set to the key
// (including the dashes).
// If a value is found without a matching key, Dictionary.Key is set to "--NoKeyN",
// where "N" represents sequential numbers.
public static Dictionary Parse(string[] args)
{
var parsedArgs = new Dictionary();
int i = 0, n = 0;
while(i < args.Length)
{
// If the first argument in this iteration starts with a dash it's an option.
if(args[i].StartsWith("-"))
{
var key = args[i++];
var value = key;
// Check to see if there's a value that goes with this option?
if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++];
parsedArgs.Add(key, value);
}
// If the first argument in this iteration doesn't start with a dash, it's a value
else
{
parsedArgs.Add("--NoKey" + n.ToString(), args[i++]);
n++;
}
}
return parsedArgs;
}
//
// Method to get an argument from the parsed command-line arguments
//
// Parameters:
// - parsedArgs: The Dictionary object returned from the Parse() method (shown above).
// - defaultValue: The default string to return if the specified key isn't in parsedArgs.
// - keys: An array of keys to look for in parsedArgs.
public static string GetArgument(
Dictionary parsedArgs, string defaultReturn, params string[] keys)
{
string retval = null;
foreach(var key in keys)
if(parsedArgs.TryGetValue(key, out retval)) break;
return retval ?? defaultReturn;
}
//
// Method to exit the application with an error.
public static void ErrorExit(string msg, int code=1)
{
Console.WriteLine("\nError");
Console.WriteLine(msg);
Environment.Exit(code);
}
}
}
```
## Additional considerations
+ After you run the example, you can see the new key pair in the [Amazon EC2 console](https://console.aws.amazon.com/ec2/#KeyPairs).
+ When you create a key pair, you must save the private key that is returned because you can't retrieve the private key later.
# Deleting key pairs
This example shows you how to use the AWS SDK for .NET to delete a key pair. The application takes the name of a key pair. It deletes the key pair and then displays all available key pairs. If you provide no command-line arguments, the application simply displays all available key pairs.
The following sections provide snippets of this example. The [complete code for the example](#delete-key-pairs-complete-code) is shown after that, and can be built and run as is.
**Topics**
+ [Delete the key pair](#delete-key-pairs-create)
+ [Display available key pairs](#delete-key-pairs-display)
+ [Complete code](#delete-key-pairs-complete-code)
## Delete the key pair
The following snippet deletes a key pair.
The example [at the end of this topic](#delete-key-pairs-complete-code) shows this snippet in use.
```
//
// Method to delete a key pair
private static async Task DeleteKeyPair(IAmazonEC2 ec2Client, string keyName)
{
await ec2Client.DeleteKeyPairAsync(new DeleteKeyPairRequest{
KeyName = keyName});
Console.WriteLine($"\nKey pair {keyName} has been deleted (if it existed).");
}
```
## Display available key pairs
The following snippet displays a list of the available key pairs.
The example [at the end of this topic](#delete-key-pairs-complete-code) shows this snippet in use.
```
//
// Method to show the key pairs that are available
private static async Task EnumerateKeyPairs(IAmazonEC2 ec2Client)
{
DescribeKeyPairsResponse response = await ec2Client.DescribeKeyPairsAsync();
Console.WriteLine("Available key pairs:");
foreach (KeyPairInfo item in response.KeyPairs)
Console.WriteLine($" {item.KeyName}");
}
```
## Complete code
This section shows relevant references and the complete code for this example.
### SDK references
NuGet packages:
+ [AWSSDK.EC2](https://www.nuget.org/packages/AWSSDK.EC2)
Programming elements:
+ Namespace [Amazon.EC2](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2.html)
Class [AmazonEC2Client](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TEC2Client.html)
+ Namespace [Amazon.EC2.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2Model.html)
Class [https://docs.aws.amazon.com/sdkfornet/v3/apidocs/](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/)
Class [DescribeKeyPairsResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TDescribeKeyPairsResponse.html)
Class [KeyPairInfo](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TKeyPairInfo.html)
### The code
```
using System;
using System.Threading.Tasks;
using Amazon.EC2;
using Amazon.EC2.Model;
namespace EC2DeleteKeyPair
{
class Program
{
static async Task Main(string[] args)
{
// Create the EC2 client
var ec2Client = new AmazonEC2Client();
if(args.Length == 1)
{
// Delete a key pair (if it exists)
await DeleteKeyPair(ec2Client, args[0]);
// Display the key pairs that are left
await EnumerateKeyPairs(ec2Client);
}
else
{
Console.WriteLine("\nUsage: EC2DeleteKeyPair keypair-name");
Console.WriteLine(" keypair-name - The name of the key pair you want to delete.");
Console.WriteLine("\nNo arguments specified.");
Console.Write(
"Do you want to see a list of the existing key pairs? ((y) or n): ");
string response = Console.ReadLine();
if((string.IsNullOrEmpty(response)) || (response.ToLower() == "y"))
await EnumerateKeyPairs(ec2Client);
}
}
//
// Method to delete a key pair
private static async Task DeleteKeyPair(IAmazonEC2 ec2Client, string keyName)
{
await ec2Client.DeleteKeyPairAsync(new DeleteKeyPairRequest{
KeyName = keyName});
Console.WriteLine($"\nKey pair {keyName} has been deleted (if it existed).");
}
//
// Method to show the key pairs that are available
private static async Task EnumerateKeyPairs(IAmazonEC2 ec2Client)
{
DescribeKeyPairsResponse response = await ec2Client.DescribeKeyPairsAsync();
Console.WriteLine("Available key pairs:");
foreach (KeyPairInfo item in response.KeyPairs)
Console.WriteLine($" {item.KeyName}");
}
}
}
```
# Seeing your Amazon EC2 Regions and Availability Zones
Amazon EC2 is hosted in multiple locations worldwide. These locations are composed of Regions and Availability Zones. Each Region is a separate geographic area that has multiple, isolated locations known as Availability Zones.
To read more about Regions and Availability Zones, see [Regions and Zones](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/).
This example shows you how to use the AWS SDK for .NET to get details about the Regions and Availability Zones related to an EC2 client. The application displays lists of the Regions and Availability Zones available to an EC2 client.
## SDK references
NuGet packages:
+ [AWSSDK.EC2](https://www.nuget.org/packages/AWSSDK.EC2)
Programming elements:
+ Namespace [Amazon.EC2](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2.html)
Class [AmazonEC2Client](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TEC2Client.html)
+ Namespace [Amazon.EC2.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2Model.html)
Class [DescribeAvailabilityZonesResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TDescribeAvailabilityZonesResponse.html)
Class [DescribeRegionsResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TDescribeRegionsResponse.html)
Class [AvailabilityZone](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TAvailabilityZone.html)
Class [Region](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TRegion.html)
```
using System;
using System.Threading.Tasks;
using Amazon.EC2;
using Amazon.EC2.Model;
namespace EC2RegionsAndZones
{
class Program
{
static async Task Main(string[] args)
{
Console.WriteLine(
"Finding the Regions and Availability Zones available to an EC2 client...");
// Create the EC2 client
var ec2Client = new AmazonEC2Client();
// Display the Regions and Availability Zones
await DescribeRegions(ec2Client);
await DescribeAvailabilityZones(ec2Client);
}
//
// Method to display Regions
private static async Task DescribeRegions(IAmazonEC2 ec2Client)
{
Console.WriteLine("\nRegions that are enabled for the EC2 client:");
DescribeRegionsResponse response = await ec2Client.DescribeRegionsAsync();
foreach (Region region in response.Regions)
Console.WriteLine(region.RegionName);
}
//
// Method to display Availability Zones
private static async Task DescribeAvailabilityZones(IAmazonEC2 ec2Client)
{
Console.WriteLine("\nAvailability Zones for the EC2 client's region:");
DescribeAvailabilityZonesResponse response =
await ec2Client.DescribeAvailabilityZonesAsync();
foreach (AvailabilityZone az in response.AvailabilityZones)
Console.WriteLine(az.ZoneName);
}
}
}
```
# Working with Amazon EC2 instances
You can use the AWS SDK for .NET to control Amazon EC2 instances with operations such as create, start, and terminate. The topics in this section provide some examples of how to do this. To read more about EC2 instances, see [Amazon EC2 instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Instances.html) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/).
For information about the APIs and prerequisites, see the parent section ([Working with Amazon EC2](ec2-apis-intro.md)).
**Topics**
+ [Launching an EC2 instance](run-instance.md)
+ [Terminating an EC2 instance](terminate-instance.md)
# Launching an Amazon EC2 instance
This example shows you how to use the AWS SDK for .NET to launch one or more identically configured Amazon EC2 instances from the same Amazon Machine Image (AMI). Using [several inputs](#run-instance-gather) that you supply, the application launches an EC2 instance and then monitors the instance until it's out of the "Pending" state.
When your EC2 instance is running, you can connect to it remotely, as described in [(optional) Connect to the instance](#connect-to-instance).
**Warning**
EC2-Classic was retired on August 15, 2022. We recommend that you migrate from EC2-Classic to a VPC. For more information, see the blog post [EC2-Classic Networking is Retiring – Here's How to Prepare](https://aws.amazon.com/blogs/aws/ec2-classic-is-retiring-heres-how-to-prepare/).
The following sections provide snippets and other information for this example. The [complete code for the example](#run-instance-complete-code) is shown after the snippets, and can be built and run as is.
**Topics**
+ [Gather what you need](#run-instance-gather)
+ [Launch an instance](#run-instance-launch)
+ [Monitor the instance](#run-instance-monitor)
+ [Complete code](#run-instance-complete-code)
+ [Additional considerations](#run-instance-additional)
+ [(optional) Connect to the instance](#connect-to-instance)
+ [Clean up](#run-instance-cleanup)
## Gather what you need
To launch an EC2 instance, you'll need several things.
+ A [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/) where the instance will be launched. If it'll be a Windows instance and you'll be connecting to it through RDP, the VPC will most likely need to have an internet gateway attached to it, as well as an entry for the internet gateway in the route table. For more information, see [Internet gateways](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html) in the *Amazon VPC User Guide*.
+ The ID of an existing subnet in the VPC where the instance will be launched. An easy way to find or create this is to sign in to the [Amazon VPC console](https://console.aws.amazon.com/vpc/home#subnets), but you can also obtain it programmatically by using the [CreateSubnetAsync](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/MEC2CreateSubnetAsyncCreateSubnetRequestCancellationToken.html) and [DescribeSubnetsAsync](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/MEC2DescribeSubnetsAsyncDescribeSubnetsRequestCancellationToken.html) methods.
**Note**
If you don't supply this parameter, the new instance is launched in the default VPC for your account.
+ The ID of an existing security group that belongs to the VPC where the instance will be launched. For more information, see [Working with security groups in Amazon EC2](security-groups.md).
+ If you want to connect to the new instance, the security group mentioned earlier must have an appropriate inbound rule that allows SSH traffic on port 22 (Linux instance) or RDP traffic on port 3389 (Windows instance). For information about how to do this see [Updating security groups](authorize-ingress.md), including the [Additional considerations](authorize-ingress.md#authorize-ingress-additional) near the end of that topic.
+ The Amazon Machine Image (AMI) that will be used to create the instance. For information about AMIs, see [Amazon Machine Images (AMIs)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/). In particular, see [Find an AMI](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/finding-an-ami.html) and [Shared AMIs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/sharing-amis.html).
+ The name of an existing EC2 key pair, which is used to connect to the new instance. For more information, see [Working with Amazon EC2 key pairs](key-pairs.md).
+ The name of the PEM file that contains the private key of the EC2 key pair mentioned earlier. The PEM file is used when you [connect remotely](#connect-to-instance) to the instance.
## Launch an instance
The following snippet launches an EC2 instance.
The example [near the end of this topic](#run-instance-complete-code) shows this snippet in use.
```
//
// Method to launch the instances
// Returns a list with the launched instance IDs
private static async Task> LaunchInstances(
IAmazonEC2 ec2Client, RunInstancesRequest requestLaunch)
{
var instanceIds = new List();
RunInstancesResponse responseLaunch =
await ec2Client.RunInstancesAsync(requestLaunch);
Console.WriteLine("\nNew instances have been created.");
foreach (Instance item in responseLaunch.Reservation.Instances)
{
instanceIds.Add(item.InstanceId);
Console.WriteLine($" New instance: {item.InstanceId}");
}
return instanceIds;
}
```
## Monitor the instance
The following snippet monitors the instance until it's out of the "Pending" state.
The example [near the end of this topic](#run-instance-complete-code) shows this snippet in use.
See the [InstanceState](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TInstanceState.html) class for the valid values of the `Instance.State.Code` property.
```
//
// Method to wait until the instances are running (or at least not pending)
private static async Task CheckState(IAmazonEC2 ec2Client, List instanceIds)
{
Console.WriteLine(
"\nWaiting for the instances to start." +
"\nPress any key to stop waiting. (Response might be slightly delayed.)");
int numberRunning;
DescribeInstancesResponse responseDescribe;
var requestDescribe = new DescribeInstancesRequest{
InstanceIds = instanceIds};
// Check every couple of seconds
int wait = 2000;
while(true)
{
// Get and check the status for each of the instances to see if it's past pending.
// Once all instances are past pending, break out.
// (For this example, we are assuming that there is only one reservation.)
Console.Write(".");
numberRunning = 0;
responseDescribe = await ec2Client.DescribeInstancesAsync(requestDescribe);
foreach(Instance i in responseDescribe.Reservations[0].Instances)
{
// Check the lower byte of State.Code property
// Code == 0 is the pending state
if((i.State.Code & 255) > 0) numberRunning++;
}
if(numberRunning == responseDescribe.Reservations[0].Instances.Count)
break;
// Wait a bit and try again (unless the user wants to stop waiting)
Thread.Sleep(wait);
if(Console.KeyAvailable)
break;
}
Console.WriteLine("\nNo more instances are pending.");
foreach(Instance i in responseDescribe.Reservations[0].Instances)
{
Console.WriteLine($"For {i.InstanceId}:");
Console.WriteLine($" VPC ID: {i.VpcId}");
Console.WriteLine($" Instance state: {i.State.Name}");
Console.WriteLine($" Public IP address: {i.PublicIpAddress}");
Console.WriteLine($" Public DNS name: {i.PublicDnsName}");
Console.WriteLine($" Key pair name: {i.KeyName}");
}
}
```
## Complete code
This section shows relevant references and the complete code for this example.
### SDK references
NuGet packages:
+ [AWSSDK.EC2](https://www.nuget.org/packages/AWSSDK.EC2)
Programming elements:
+ Namespace [Amazon.EC2](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2.html)
Class [AmazonEC2Client](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TEC2Client.html)
Class [InstanceType](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TInstanceType.html)
+ Namespace [Amazon.EC2.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2Model.html)
Class [DescribeInstancesRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TDescribeInstancesRequest.html)
Class [DescribeInstancesResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TDescribeInstancesResponse.html)
Class [Instance](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TInstance.html)
Class [InstanceNetworkInterfaceSpecification](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TInstanceNetworkInterfaceSpecification.html)
Class [RunInstancesRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TRunInstancesRequest.html)
Class [RunInstancesResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TRunInstancesResponse.html)
### The code
```
using System;
using System.Threading;
using System.Threading.Tasks;
using System.Collections.Generic;
using Amazon.EC2;
using Amazon.EC2.Model;
namespace EC2LaunchInstance
{
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class to launch an EC2 instance
class Program
{
static async Task Main(string[] args)
{
// Parse the command line and show help if necessary
var parsedArgs = CommandLine.Parse(args);
if(parsedArgs.Count == 0)
{
PrintHelp();
return;
}
// Get the application arguments from the parsed list
string groupID =
CommandLine.GetArgument(parsedArgs, null, "-g", "--group-id");
string ami =
CommandLine.GetArgument(parsedArgs, null, "-a", "--ami-id");
string keyPairName =
CommandLine.GetArgument(parsedArgs, null, "-k", "--keypair-name");
string subnetID =
CommandLine.GetArgument(parsedArgs, null, "-s", "--subnet-id");
if( (string.IsNullOrEmpty(groupID) || !groupID.StartsWith("sg-"))
|| (string.IsNullOrEmpty(ami) || !ami.StartsWith("ami-"))
|| (string.IsNullOrEmpty(keyPairName))
|| (!string.IsNullOrEmpty(subnetID) && !subnetID.StartsWith("subnet-")))
CommandLine.ErrorExit(
"\nOne or more of the required arguments is missing or incorrect." +
"\nRun the command with no arguments to see help.");
// Create an EC2 client
var ec2Client = new AmazonEC2Client();
// Create an object with the necessary properties
RunInstancesRequest request = GetRequestData(groupID, ami, keyPairName, subnetID);
// Launch the instances and wait for them to start running
var instanceIds = await LaunchInstances(ec2Client, request);
await CheckState(ec2Client, instanceIds);
}
//
// Method to put together the properties needed to launch the instance.
private static RunInstancesRequest GetRequestData(
string groupID, string ami, string keyPairName, string subnetID)
{
// Common properties
var groupIDs = new List() { groupID };
var request = new RunInstancesRequest()
{
// The first three of these would be additional command-line arguments or similar.
InstanceType = InstanceType.T1Micro,
MinCount = 1,
MaxCount = 1,
ImageId = ami,
KeyName = keyPairName
};
// Properties specifically for EC2 in a VPC.
if(!string.IsNullOrEmpty(subnetID))
{
request.NetworkInterfaces =
new List() {
new InstanceNetworkInterfaceSpecification() {
DeviceIndex = 0,
SubnetId = subnetID,
Groups = groupIDs,
AssociatePublicIpAddress = true
}
};
}
// Properties specifically for EC2-Classic
else
{
request.SecurityGroupIds = groupIDs;
}
return request;
}
//
// Method to launch the instances
// Returns a list with the launched instance IDs
private static async Task> LaunchInstances(
IAmazonEC2 ec2Client, RunInstancesRequest requestLaunch)
{
var instanceIds = new List();
RunInstancesResponse responseLaunch =
await ec2Client.RunInstancesAsync(requestLaunch);
Console.WriteLine("\nNew instances have been created.");
foreach (Instance item in responseLaunch.Reservation.Instances)
{
instanceIds.Add(item.InstanceId);
Console.WriteLine($" New instance: {item.InstanceId}");
}
return instanceIds;
}
//
// Method to wait until the instances are running (or at least not pending)
private static async Task CheckState(IAmazonEC2 ec2Client, List instanceIds)
{
Console.WriteLine(
"\nWaiting for the instances to start." +
"\nPress any key to stop waiting. (Response might be slightly delayed.)");
int numberRunning;
DescribeInstancesResponse responseDescribe;
var requestDescribe = new DescribeInstancesRequest{
InstanceIds = instanceIds};
// Check every couple of seconds
int wait = 2000;
while(true)
{
// Get and check the status for each of the instances to see if it's past pending.
// Once all instances are past pending, break out.
// (For this example, we are assuming that there is only one reservation.)
Console.Write(".");
numberRunning = 0;
responseDescribe = await ec2Client.DescribeInstancesAsync(requestDescribe);
foreach(Instance i in responseDescribe.Reservations[0].Instances)
{
// Check the lower byte of State.Code property
// Code == 0 is the pending state
if((i.State.Code & 255) > 0) numberRunning++;
}
if(numberRunning == responseDescribe.Reservations[0].Instances.Count)
break;
// Wait a bit and try again (unless the user wants to stop waiting)
Thread.Sleep(wait);
if(Console.KeyAvailable)
break;
}
Console.WriteLine("\nNo more instances are pending.");
foreach(Instance i in responseDescribe.Reservations[0].Instances)
{
Console.WriteLine($"For {i.InstanceId}:");
Console.WriteLine($" VPC ID: {i.VpcId}");
Console.WriteLine($" Instance state: {i.State.Name}");
Console.WriteLine($" Public IP address: {i.PublicIpAddress}");
Console.WriteLine($" Public DNS name: {i.PublicDnsName}");
Console.WriteLine($" Key pair name: {i.KeyName}");
}
}
//
// Command-line help
private static void PrintHelp()
{
Console.WriteLine(
"\nUsage: EC2LaunchInstance -g -a -k [-s ]" +
"\n -g, --group-id: The ID of the security group." +
"\n -a, --ami-id: The ID of an Amazon Machine Image." +
"\n -k, --keypair-name - The name of a key pair." +
"\n -s, --subnet-id: The ID of a subnet. Required only for EC2 in a VPC.");
}
}
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class that represents a command line on the console or terminal.
// (This is the same for all examples. When you have seen it once, you can ignore it.)
static class CommandLine
{
//
// Method to parse a command line of the form: "--key value" or "-k value".
//
// Parameters:
// - args: The command-line arguments passed into the application by the system.
//
// Returns:
// A Dictionary with string Keys and Values.
//
// If a key is found without a matching value, Dictionary.Value is set to the key
// (including the dashes).
// If a value is found without a matching key, Dictionary.Key is set to "--NoKeyN",
// where "N" represents sequential numbers.
public static Dictionary Parse(string[] args)
{
var parsedArgs = new Dictionary();
int i = 0, n = 0;
while(i < args.Length)
{
// If the first argument in this iteration starts with a dash it's an option.
if(args[i].StartsWith("-"))
{
var key = args[i++];
var value = key;
// Check to see if there's a value that goes with this option?
if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++];
parsedArgs.Add(key, value);
}
// If the first argument in this iteration doesn't start with a dash, it's a value
else
{
parsedArgs.Add("--NoKey" + n.ToString(), args[i++]);
n++;
}
}
return parsedArgs;
}
//
// Method to get an argument from the parsed command-line arguments
//
// Parameters:
// - parsedArgs: The Dictionary object returned from the Parse() method (shown above).
// - defaultValue: The default string to return if the specified key isn't in parsedArgs.
// - keys: An array of keys to look for in parsedArgs.
public static string GetArgument(
Dictionary parsedArgs, string defaultReturn, params string[] keys)
{
string retval = null;
foreach(var key in keys)
if(parsedArgs.TryGetValue(key, out retval)) break;
return retval ?? defaultReturn;
}
//
// Method to exit the application with an error.
public static void ErrorExit(string msg, int code=1)
{
Console.WriteLine("\nError");
Console.WriteLine(msg);
Environment.Exit(code);
}
}
}
```
## Additional considerations
+ When checking the state of an EC2 instance, you can add a filter to the `Filter` property of the [DescribeInstancesRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TDescribeInstancesRequest.html) object. Using this technique, you can limit the request to certain instances; for example, instances with a particular user-specified tag.
+ For brevity, some properties were given typical values. Any or all of these properties can instead be determined programmatically or by user input.
+ The values you can use for the `MinCount` and `MaxCount` properties of the [RunInstancesRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TRunInstancesRequest.html) object are determined by the target Availability Zone and the maximum number of instances you’re allowed for the instance type. For more information, see [How many instances can I run in Amazon EC2](https://aws.amazon.com/ec2/faqs/#How_many_instances_can_I_run_in_Amazon_EC2) in the Amazon EC2 General FAQ.
+ If you want to use a different instance type than this example, there are several instance types to choose from. For more information see [Amazon EC2 instance types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/). Also see [Instance Type Details](https://aws.amazon.com/ec2/instance-types/) and [Instance Type Explorer](https://aws.amazon.com/ec2/instance-explorer/).
+ You can also attach an [IAM role](net-dg-hosm.md) to an instance when you launch it. To do so, create an [IamInstanceProfileSpecification](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TIamInstanceProfileSpecification.html) object whose `Name` property is set to the name of an IAM role. Then add that object to the `IamInstanceProfile` property of the [RunInstancesRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TRunInstancesRequest.html) object.
**Note**
To launch an EC2 instance that has an IAM role attached, an IAM user's configuration must include certain permissions. For more information about the required permissions, see the [Grant a user permission to pass an IAM role to an instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#permission-to-pass-iam-roles) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/).
## (optional) Connect to the instance
After an instance is running, you can connect to it remotely by using the appropriate remote client. For both Linux and Windows instances, you need the instance's public IP address or public DNS name. You also need the following.
**For Linux instances**
You can use an SSH client to connect to your Linux instance. Make sure that the security group you used when you launched the instance allows SSH traffic on port 22, as described in [Updating security groups](authorize-ingress.md).
You also need the private portion of the key pair you used to launch the instance; that is, the PEM file.
For more information, see [Connect to your Linux instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-to-linux-instance.html) in the Amazon EC2 User Guide.
**For Windows instances**
You can use an RDP client to connect to your instance. Make sure that the security group you used when you launched the instance allows RDP traffic on port 3389, as described in [Updating security groups](authorize-ingress.md).
You also need the Administrator password. You can obtain this by using the following example code, which requires the instance ID and the private portion of the key pair used to launch the instance; that is, the PEM file.
For more information, see [Connect to your Windows instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connecting_to_windows_instance.html) in the Amazon EC2 User Guide.
**Warning**
This example code returns the plaintext Administrator password for your instance.
### SDK references
NuGet packages:
+ [AWSSDK.EC2](https://www.nuget.org/packages/AWSSDK.EC2)
Programming elements:
+ Namespace [Amazon.EC2](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2.html)
Class [AmazonEC2Client](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TEC2Client.html)
+ Namespace [Amazon.EC2.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2Model.html)
Class [GetPasswordDataRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TGetPasswordDataRequest.html)
Class [GetPasswordDataResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TGetPasswordDataResponse.html)
### The code
```
using System;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;
using Amazon.EC2;
using Amazon.EC2.Model;
namespace EC2GetWindowsPassword
{
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class to get the Administrator password of a Windows EC2 instance
class Program
{
static async Task Main(string[] args)
{
// Parse the command line and show help if necessary
var parsedArgs = CommandLine.Parse(args);
if(parsedArgs.Count == 0)
{
PrintHelp();
return;
}
// Get the application arguments from the parsed list
string instanceID =
CommandLine.GetArgument(parsedArgs, null, "-i", "--instance-id");
string pemFileName =
CommandLine.GetArgument(parsedArgs, null, "-p", "--pem-filename");
if( (string.IsNullOrEmpty(instanceID) || !instanceID.StartsWith("i-"))
|| (string.IsNullOrEmpty(pemFileName) || !pemFileName.EndsWith(".pem")))
CommandLine.ErrorExit(
"\nOne or more of the required arguments is missing or incorrect." +
"\nRun the command with no arguments to see help.");
// Create the EC2 client
var ec2Client = new AmazonEC2Client();
// Get and display the password
string password = await GetPassword(ec2Client, instanceID, pemFileName);
Console.WriteLine($"\nPassword: {password}");
}
//
// Method to get the administrator password of a Windows EC2 instance
private static async Task GetPassword(
IAmazonEC2 ec2Client, string instanceID, string pemFilename)
{
string password = string.Empty;
GetPasswordDataResponse response =
await ec2Client.GetPasswordDataAsync(new GetPasswordDataRequest{
InstanceId = instanceID});
if(response.PasswordData != null)
{
password = response.GetDecryptedPassword(File.ReadAllText(pemFilename));
}
else
{
Console.WriteLine($"\nThe password is not available for instance {instanceID}.");
Console.WriteLine($"If this is a Windows instance, the password might not be ready.");
}
return password;
}
//
// Command-line help
private static void PrintHelp()
{
Console.WriteLine(
"\nUsage: EC2GetWindowsPassword -i -p pem-filename" +
"\n -i, --instance-id: The name of the EC2 instance." +
"\n -p, --pem-filename: The name of the PEM file with the private key.");
}
}
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class that represents a command line on the console or terminal.
// (This is the same for all examples. When you have seen it once, you can ignore it.)
static class CommandLine
{
//
// Method to parse a command line of the form: "--key value" or "-k value".
//
// Parameters:
// - args: The command-line arguments passed into the application by the system.
//
// Returns:
// A Dictionary with string Keys and Values.
//
// If a key is found without a matching value, Dictionary.Value is set to the key
// (including the dashes).
// If a value is found without a matching key, Dictionary.Key is set to "--NoKeyN",
// where "N" represents sequential numbers.
public static Dictionary Parse(string[] args)
{
var parsedArgs = new Dictionary();
int i = 0, n = 0;
while(i < args.Length)
{
// If the first argument in this iteration starts with a dash it's an option.
if(args[i].StartsWith("-"))
{
var key = args[i++];
var value = key;
// Check to see if there's a value that goes with this option?
if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++];
parsedArgs.Add(key, value);
}
// If the first argument in this iteration doesn't start with a dash, it's a value
else
{
parsedArgs.Add("--NoKey" + n.ToString(), args[i++]);
n++;
}
}
return parsedArgs;
}
//
// Method to get an argument from the parsed command-line arguments
//
// Parameters:
// - parsedArgs: The Dictionary object returned from the Parse() method (shown above).
// - defaultValue: The default string to return if the specified key isn't in parsedArgs.
// - keys: An array of keys to look for in parsedArgs.
public static string GetArgument(
Dictionary parsedArgs, string defaultReturn, params string[] keys)
{
string retval = null;
foreach(var key in keys)
if(parsedArgs.TryGetValue(key, out retval)) break;
return retval ?? defaultReturn;
}
//
// Method to exit the application with an error.
public static void ErrorExit(string msg, int code=1)
{
Console.WriteLine("\nError");
Console.WriteLine(msg);
Environment.Exit(code);
}
}
}
```
## Clean up
When you no longer need your EC2 instance, be sure to terminate it, as described in [Terminating an Amazon EC2 instance](terminate-instance.md).
# Terminating an Amazon EC2 instance
When you no longer need one or more of your Amazon EC2 instances, you can terminate them.
This example shows you how to use the AWS SDK for .NET to terminate EC2 instances. It takes an instance ID as input.
## SDK references
NuGet packages:
+ [AWSSDK.EC2](https://www.nuget.org/packages/AWSSDK.EC2)
Programming elements:
+ Namespace [Amazon.EC2](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2.html)
Class [AmazonEC2Client](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TEC2Client.html)
+ Namespace [Amazon.EC2.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2Model.html)
Class [TerminateInstancesRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TTerminateInstancesRequest.html)
Class [TerminateInstancesResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TTerminateInstancesResponse.html)
```
using System;
using System.Threading.Tasks;
using System.Collections.Generic;
using Amazon.EC2;
using Amazon.EC2.Model;
namespace EC2TerminateInstance
{
class Program
{
static async Task Main(string[] args)
{
if((args.Length == 1) && (args[0].StartsWith("i-")))
{
// Terminate the instance
var ec2Client = new AmazonEC2Client();
await TerminateInstance(ec2Client, args[0]);
}
else
{
Console.WriteLine("\nCommand-line argument missing or incorrect.");
Console.WriteLine("\nUsage: EC2TerminateInstance instance-ID");
Console.WriteLine(" instance-ID - The EC2 instance you want to terminate.");
return;
}
}
//
// Method to terminate an EC2 instance
private static async Task TerminateInstance(IAmazonEC2 ec2Client, string instanceID)
{
var request = new TerminateInstancesRequest{
InstanceIds = new List() { instanceID }};
TerminateInstancesResponse response =
await ec2Client.TerminateInstancesAsync(new TerminateInstancesRequest{
InstanceIds = new List() { instanceID }
});
foreach (InstanceStateChange item in response.TerminatingInstances)
{
Console.WriteLine("Terminated instance: " + item.InstanceId);
Console.WriteLine("Instance state: " + item.CurrentState.Name);
}
}
}
}
```
After you run the example, it's a good idea to sign in to the [Amazon EC2 console](https://console.aws.amazon.com/ec2/) to verify that the [EC2 instance](https://console.aws.amazon.com/ec2/v2/home#Instances) has been terminated.
# Amazon EC2 Spot Instance tutorial
This tutorial shows you how to use the AWS SDK for .NET to manage Amazon EC2 Spot Instances.
## Overview
Spot Instances enable you to request unused Amazon EC2 capacity for less than the On-Demand price. This can significantly lower your EC2 costs for applications that can be interrupted.
The following is a high-level summary of how Spot Instances are requested and used.
1. Create a Spot Instance request, specifying the maximum price you are willing to pay.
1. When the request is fulfilled, run the instance as you would any other Amazon EC2 instance.
1. Run the instance as long as you want and then terminate it, unless the *Spot Price* changes such that the instance is terminated for you.
1. Clean up the Spot Instance request when you no longer need it so that Spot Instances are no longer created.
This has been a very high level overview of Spot Instances. To gain a better understanding of Spot Instances, see [Spot Instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-spot-instances.html) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/).
## About this tutorial
As you follow this tutorial, you use the AWS SDK for .NET to do the following:
+ Create a Spot Instance request
+ Determine when the Spot Instance request has been fulfilled
+ Cancel the Spot Instance request
+ Terminate associated instances
The following sections provide snippets and other information for this example. The [complete code for the example](#tutor-spot-net-main) is shown after the snippets, and can be built and run as is.
**Topics**
+ [Overview](#tutor-spot-net-overview)
+ [About this tutorial](#about-spot-instances-tutorial)
+ [Prerequisites](#tutor-spot-net-prereq)
+ [Gather what you need](#tutor-spot-net-gather)
+ [Creating a Spot Instance request](#tutor-spot-net-submit)
+ [Determine the state of your Spot Instance request](#tutor-spot-net-request-state)
+ [Clean up your Spot Instance requests](#tutor-spot-net-clean-up-request)
+ [Clean up your Spot Instances](#tutor-spot-net-clean-up-instance)
+ [Complete code](#tutor-spot-net-main)
+ [Additional considerations](#tutor-spot-net-additional)
## Prerequisites
For information about the APIs and prerequisites, see the parent section ([Working with Amazon EC2](ec2-apis-intro.md)).
## Gather what you need
To create a Spot Instance request, you'll need several things.
+ The number of instances and their instance type. There are several instance types to choose from. For more information, see [Amazon EC2 instance types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/). Also see [Instance Type Details](https://aws.amazon.com/ec2/instance-types/) and [Instance Type Explorer](https://aws.amazon.com/ec2/instance-explorer/).
The default number for this tutorial is 1.
+ The Amazon Machine Image (AMI) that will be used to create the instance. For information about AMIs, see [Amazon Machine Images (AMIs)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/). In particular, see [Find an AMI](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/finding-an-ami.html) and [Shared AMIs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/sharing-amis.html).
+ The maximum price that you're willing to pay per instance hour. You can see the prices for all instance types (for both On-Demand Instances and Spot Instances) on the [Amazon EC2 pricing page](https://aws.amazon.com/ec2/pricing/). The default price for this tutorial is explained later.
+ If you want to connect remotely to an instance, a security group with the appropriate configuration and resources. This is described in [Working with security groups in Amazon EC2](security-groups.md) and the information about [gathering what you need](run-instance.md#run-instance-gather) and [connecting to an instance](run-instance.md#connect-to-instance) in [Launching an Amazon EC2 instance](run-instance.md). For simplicity, this tutorial uses the security group named **default** that all newer AWS accounts have.
There are many ways to approach requesting Spot Instances. The following are common strategies:
+ Make requests that are sure to cost less than on-demand pricing.
+ Make requests based on the value of the resulting computation.
+ Make requests so as to acquire computing capacity as quickly as possible.
The following explanations refer to the [Spot Instance pricing history](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-spot-instances-history.html) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/).
### Reduce cost below On-Demand
You have a batch processing job that will take a number of hours or days to run. However, you are flexible with respect to when it starts and ends. You want to see if you can complete it for less than the cost of On-Demand Instances.
You examine the Spot Price history for instance types by using either the Amazon EC2 console or the Amazon EC2 API. After you've analyzed the price history for your desired instance type in a given Availability Zone, you have two alternative approaches for your request:
+ Specify a request at the upper end of the range of Spot Prices, which are still below the On-Demand price, anticipating that your one-time Spot Instance request would most likely be fulfilled and run for enough consecutive compute time to complete the job.
+ Specify a request at the lower end of the price range, and plan to combine many instances launched over time through a persistent request. The instances would run long enough, in aggregate, to complete the job at an even lower total cost.
### Pay no more than the value of the result
You have a data processing job to run. You understand the value of the job's results well enough to know how much they're worth in terms of computing costs.
After you've analyzed the Spot Price history for your instance type, you choose a price at which the cost of the computing time is no more than the value of the job's results. You create a persistent request and allow it to run intermittently as the Spot Price fluctuates at or below your request.
### Acquire computing capacity quickly
You have an unanticipated, short-term need for additional capacity that's not available through On-Demand Instances. After you've analyzed the Spot Price history for your instance type, you choose a price above the highest historical price to greatly improve the likelihood that your request will be fulfilled quickly and continue computing until it's complete.
After you have gathered what you need and chosen a strategy, you are ready to request a Spot Instance. For this tutorial the default maximum spot-instance price is set to be the same as the On-Demand price (which is \$10.003 for this tutorial). Setting the price in this way maximizes the chances that the request will be fulfilled.
## Creating a Spot Instance request
The following snippet shows you how to create a Spot Instance request with the elements you gathered earlier.
The example [at the end of this topic](#tutor-spot-net-main) shows this snippet in use.
```
//
// Method to create a Spot Instance request
private static async Task CreateSpotInstanceRequest(
IAmazonEC2 ec2Client, string amiId, string securityGroupName,
InstanceType instanceType, string spotPrice, int instanceCount)
{
var launchSpecification = new LaunchSpecification{
ImageId = amiId,
InstanceType = instanceType
};
launchSpecification.SecurityGroups.Add(securityGroupName);
var request = new RequestSpotInstancesRequest{
SpotPrice = spotPrice,
InstanceCount = instanceCount,
LaunchSpecification = launchSpecification
};
RequestSpotInstancesResponse result =
await ec2Client.RequestSpotInstancesAsync(request);
return result.SpotInstanceRequests[0];
}
```
The important value returned from this method is the Spot Instance request ID, which is contained in the `SpotInstanceRequestId` member of the returned [SpotInstanceRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TSpotInstanceRequest.html) object.
**Note**
You will be charged for any Spot Instances that are launched. To avoid unnecessary costs be sure to [cancel any requests](#tutor-spot-net-clean-up-request) and [terminate any instances](#tutor-spot-net-clean-up-instance).
## Determine the state of your Spot Instance request
The following snippet shows you how to get information about your Spot Instance request. You can use that information to make certain decisions in your code, such as whether to continue waiting for a Spot Instance request to be fulfilled.
The example [at the end of this topic](#tutor-spot-net-main) shows this snippet in use.
```
//
// Method to get information about a Spot Instance request, including the status,
// instance ID, etc.
// It gets the information for a specific request (as opposed to all requests).
private static async Task GetSpotInstanceRequestInfo(
IAmazonEC2 ec2Client, string requestId)
{
var describeRequest = new DescribeSpotInstanceRequestsRequest();
describeRequest.SpotInstanceRequestIds.Add(requestId);
DescribeSpotInstanceRequestsResponse describeResponse =
await ec2Client.DescribeSpotInstanceRequestsAsync(describeRequest);
return describeResponse.SpotInstanceRequests[0];
}
```
The method returns information about the Spot Instance request such as the instance ID, it's state, and the status code. For more information about the status codes for Spot Instance requests, see [Spot request status](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-bid-status.html#spot-instance-bid-status-understand) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/).
## Clean up your Spot Instance requests
When you no longer need to request Spot Instances, it's important to cancel any outstanding requests to prevent those requests from being re-fulfilled. The following snippet shows you how to cancel a Spot Instance request.
The example [at the end of this topic](#tutor-spot-net-main) shows this snippet in use.
```
//
// Method to cancel a Spot Instance request
private static async Task CancelSpotInstanceRequest(
IAmazonEC2 ec2Client, string requestId)
{
var cancelRequest = new CancelSpotInstanceRequestsRequest();
cancelRequest.SpotInstanceRequestIds.Add(requestId);
await ec2Client.CancelSpotInstanceRequestsAsync(cancelRequest);
}
```
## Clean up your Spot Instances
To avoid unnecessary costs, it's important that you terminate any instances that were started from Spot Instance requests; simply canceling Spot Instance requests will not terminate your instances, which means that you'll continue to be charged for them. The following snippet shows you how to terminate an instance after you obtain the instance identifier for an active Spot Instance.
The example [at the end of this topic](#tutor-spot-net-main) shows this snippet in use.
```
//
// Method to terminate a Spot Instance
private static async Task TerminateSpotInstance(
IAmazonEC2 ec2Client, string requestId)
{
var describeRequest = new DescribeSpotInstanceRequestsRequest();
describeRequest.SpotInstanceRequestIds.Add(requestId);
// Retrieve the Spot Instance request to check for running instances.
DescribeSpotInstanceRequestsResponse describeResponse =
await ec2Client.DescribeSpotInstanceRequestsAsync(describeRequest);
// If there are any running instances, terminate them
if( (describeResponse.SpotInstanceRequests[0].Status.Code
== "request-canceled-and-instance-running")
|| (describeResponse.SpotInstanceRequests[0].State == SpotInstanceState.Active))
{
TerminateInstancesResponse response =
await ec2Client.TerminateInstancesAsync(new TerminateInstancesRequest{
InstanceIds = new List(){
describeResponse.SpotInstanceRequests[0].InstanceId } });
foreach (InstanceStateChange item in response.TerminatingInstances)
{
Console.WriteLine($"\n Terminated instance: {item.InstanceId}");
Console.WriteLine($" Instance state: {item.CurrentState.Name}\n");
}
}
}
```
## Complete code
The following code example calls the methods described earlier to create and cancel a Spot Instance request and terminate a Spot Instance.
### SDK references
NuGet packages:
+ [AWSSDK.EC2](https://www.nuget.org/packages/AWSSDK.EC2)
Programming elements:
+ Namespace [Amazon.EC2](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2.html)
Class [AmazonEC2Client](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TEC2Client.html)
Class [InstanceType](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TInstanceType.html)
+ Namespace [Amazon.EC2.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/NEC2Model.html)
Class [CancelSpotInstanceRequestsRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TCancelSpotInstanceRequestsRequest.html)
Class [DescribeSpotInstanceRequestsRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TDescribeSpotInstanceRequestsRequest.html)
Class [DescribeSpotInstanceRequestsResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TDescribeSpotInstanceRequestsResponse.html)
Class [InstanceStateChange](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TInstanceStateChange.html)
Class [LaunchSpecification](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TLaunchSpecification.html)
Class [RequestSpotInstancesRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TRequestSpotInstancesRequest.html)
Class [RequestSpotInstancesResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TRequestSpotInstancesResponse.html)
Class [SpotInstanceRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TSpotInstanceRequest.html)
Class [TerminateInstancesRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TTerminateInstancesRequest.html)
Class [TerminateInstancesResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/EC2/TTerminateInstancesResponse.html)
### The code
```
using System;
using System.Threading;
using System.Threading.Tasks;
using System.Collections.Generic;
using Amazon.EC2;
using Amazon.EC2.Model;
namespace EC2SpotInstanceRequests
{
class Program
{
static async Task Main(string[] args)
{
// Some default values.
// These could be made into command-line arguments instead.
var instanceType = InstanceType.T1Micro;
string securityGroupName = "default";
string spotPrice = "0.003";
int instanceCount = 1;
// Parse the command line arguments
if((args.Length != 1) || (!args[0].StartsWith("ami-")))
{
Console.WriteLine("\nUsage: EC2SpotInstanceRequests ami");
Console.WriteLine(" ami: the Amazon Machine Image to use for the Spot Instances.");
return;
}
// Create the Amazon EC2 client.
var ec2Client = new AmazonEC2Client();
// Create the Spot Instance request and record its ID
Console.WriteLine("\nCreating spot instance request...");
var req = await CreateSpotInstanceRequest(
ec2Client, args[0], securityGroupName, instanceType, spotPrice, instanceCount);
string requestId = req.SpotInstanceRequestId;
// Wait for an EC2 Spot Instance to become active
Console.WriteLine(
$"Waiting for Spot Instance request with ID {requestId} to become active...");
int wait = 1;
var start = DateTime.Now;
while(true)
{
Console.Write(".");
// Get and check the status to see if the request has been fulfilled.
var requestInfo = await GetSpotInstanceRequestInfo(ec2Client, requestId);
if(requestInfo.Status.Code == "fulfilled")
{
Console.WriteLine($"\nSpot Instance request {requestId} " +
$"has been fulfilled by instance {requestInfo.InstanceId}.\n");
break;
}
// Wait a bit and try again, longer each time (1, 2, 4, ...)
Thread.Sleep(wait);
wait = wait * 2;
}
// Show the user how long it took to fulfill the Spot Instance request.
TimeSpan span = DateTime.Now.Subtract(start);
Console.WriteLine($"That took {span.TotalMilliseconds} milliseconds");
// Perform actions here as needed.
// For this example, simply wait for the user to hit a key.
// That gives them a chance to look at the EC2 console to see
// the running instance if they want to.
Console.WriteLine("Press any key to start the cleanup...");
Console.ReadKey(true);
// Cancel the request.
// Do this first to make sure that the request can't be re-fulfilled
// once the Spot Instance has been terminated.
Console.WriteLine("Canceling Spot Instance request...");
await CancelSpotInstanceRequest(ec2Client, requestId);
// Terminate the Spot Instance that's running.
Console.WriteLine("Terminating the running Spot Instance...");
await TerminateSpotInstance(ec2Client, requestId);
Console.WriteLine("Done. Press any key to exit...");
Console.ReadKey(true);
}
//
// Method to create a Spot Instance request
private static async Task CreateSpotInstanceRequest(
IAmazonEC2 ec2Client, string amiId, string securityGroupName,
InstanceType instanceType, string spotPrice, int instanceCount)
{
var launchSpecification = new LaunchSpecification{
ImageId = amiId,
InstanceType = instanceType
};
launchSpecification.SecurityGroups.Add(securityGroupName);
var request = new RequestSpotInstancesRequest{
SpotPrice = spotPrice,
InstanceCount = instanceCount,
LaunchSpecification = launchSpecification
};
RequestSpotInstancesResponse result =
await ec2Client.RequestSpotInstancesAsync(request);
return result.SpotInstanceRequests[0];
}
//
// Method to get information about a Spot Instance request, including the status,
// instance ID, etc.
// It gets the information for a specific request (as opposed to all requests).
private static async Task GetSpotInstanceRequestInfo(
IAmazonEC2 ec2Client, string requestId)
{
var describeRequest = new DescribeSpotInstanceRequestsRequest();
describeRequest.SpotInstanceRequestIds.Add(requestId);
DescribeSpotInstanceRequestsResponse describeResponse =
await ec2Client.DescribeSpotInstanceRequestsAsync(describeRequest);
return describeResponse.SpotInstanceRequests[0];
}
//
// Method to cancel a Spot Instance request
private static async Task CancelSpotInstanceRequest(
IAmazonEC2 ec2Client, string requestId)
{
var cancelRequest = new CancelSpotInstanceRequestsRequest();
cancelRequest.SpotInstanceRequestIds.Add(requestId);
await ec2Client.CancelSpotInstanceRequestsAsync(cancelRequest);
}
//
// Method to terminate a Spot Instance
private static async Task TerminateSpotInstance(
IAmazonEC2 ec2Client, string requestId)
{
var describeRequest = new DescribeSpotInstanceRequestsRequest();
describeRequest.SpotInstanceRequestIds.Add(requestId);
// Retrieve the Spot Instance request to check for running instances.
DescribeSpotInstanceRequestsResponse describeResponse =
await ec2Client.DescribeSpotInstanceRequestsAsync(describeRequest);
// If there are any running instances, terminate them
if( (describeResponse.SpotInstanceRequests[0].Status.Code
== "request-canceled-and-instance-running")
|| (describeResponse.SpotInstanceRequests[0].State == SpotInstanceState.Active))
{
TerminateInstancesResponse response =
await ec2Client.TerminateInstancesAsync(new TerminateInstancesRequest{
InstanceIds = new List(){
describeResponse.SpotInstanceRequests[0].InstanceId } });
foreach (InstanceStateChange item in response.TerminatingInstances)
{
Console.WriteLine($"\n Terminated instance: {item.InstanceId}");
Console.WriteLine($" Instance state: {item.CurrentState.Name}\n");
}
}
}
}
}
```
## Additional considerations
+ After you run the tutorial, it's a good idea to sign in to the [Amazon EC2 console](https://console.aws.amazon.com/ec2/) to verify that the [Spot Instance request](https://console.aws.amazon.com/ec2/home#SpotInstances:) has been canceled and that the [Spot Instance](https://console.aws.amazon.com/ec2/v2/home#Instances) has been terminated.
# Accessing AWS Identity and Access Management (IAM) with the AWS SDK for .NET
The AWS SDK for .NET supports [AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/), which is a web service that enables AWS customers to manage users and user permissions in AWS.
An AWS Identity and Access Management (IAM) *user* is an entity that you create in AWS. The entity represents a person or application that interacts with AWS. For more information about IAM users, see [IAM Users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html) and [IAM and STS Limits](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-limits.html) in the IAM User Guide.
You grant permissions to a user by creating an IAM *policy*. The policy contains a *policy document* that lists the actions that a user can perform and the resources those actions can affect. For more information about IAM policies, see [Policies and Permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) in the *IAM User Guide*.
**Warning**
To avoid security risks, don't use IAM users for authentication when developing purpose-built software or working with real data. Instead, use federation with an identity provider such as [AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html).
## APIs
The AWS SDK for .NET provides APIs for IAM clients. The APIs enable you to work with IAM features such as users, roles, and access keys.
This section contains a small number of examples that show you the patterns you can follow when working with these APIs. To view the full set of APIs, see the [AWS SDK for .NET API Reference](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/) (and scroll to "Amazon.IdentityManagement").
This section also contains [an example](net-dg-hosm.md) that shows you how to attach an IAM role to Amazon EC2 instances to make managing credentials easier.
The IAM APIs are provided by the [AWSSDK.IdentityManagement](https://www.nuget.org/packages/AWSSDK.IdentityManagement) NuGet package.
## Prerequisites
Before you begin, be sure you have [set up your environment and project](net-dg-config.md). Also review the information in [SDK features](net-dg-sdk-features.md).
## Topics
**Topics**
+ [APIs](#w2aac19c15c19c13)
+ [Prerequisites](#w2aac19c15c19c15)
+ [Topics](#w2aac19c15c19c17)
+ [Creating managed policies from JSON](iam-policies-create-json.md)
+ [Displaying policy documents](iam-policies-display.md)
+ [Granting access with a role](net-dg-hosm.md)
# Creating IAM managed policies from JSON
This example shows you how to use the AWS SDK for .NET to create an [IAM managed policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) from a given policy document in JSON. The application creates an IAM client object, reads the policy document from a file, and then creates the policy.
**Note**
For an example policy document in JSON, see the [additional considerations](#iam-policies-create-json-additional) at the end of this topic.
The following sections provide snippets of this example. The [complete code for the example](#iam-policies-create-json-complete-code) is shown after that, and can be built and run as is.
**Topics**
+ [Create the policy](#iam-policies-create-json-create)
+ [Complete code](#iam-policies-create-json-complete-code)
+ [Additional considerations](#iam-policies-create-json-additional)
## Create the policy
The following snippet creates an IAM managed policy with the given name and policy document.
The example [at the end of this topic](#iam-policies-create-json-complete-code) shows this snippet in use.
```
//
// Method to create an IAM policy from a JSON file
private static async Task CreateManagedPolicy(
IAmazonIdentityManagementService iamClient, string policyName, string jsonFilename)
{
return await iamClient.CreatePolicyAsync(new CreatePolicyRequest{
PolicyName = policyName,
PolicyDocument = File.ReadAllText(jsonFilename)});
}
```
## Complete code
This section shows relevant references and the complete code for this example.
### SDK references
NuGet packages:
+ [AWSSDK.IdentityManagement](https://www.nuget.org/packages/AWSSDK.IdentityManagement)
Programming elements:
+ Namespace [Amazon.IdentityManagement](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IAM/NIAM.html)
Class [AmazonIdentityManagementServiceClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IAM/TIAMServiceClient.html)
+ Namespace [Amazon.IdentityManagement.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IAM/NIAMModel.html)
Class [CreatePolicyRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IAM/TCreatePolicyRequest.html)
Class [CreatePolicyResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IAM/TCreatePolicyResponse.html)
### The code
```
using System;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;
using Amazon.IdentityManagement;
using Amazon.IdentityManagement.Model;
namespace IamCreatePolicyFromJson
{
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class to create an IAM policy with a given policy document
class Program
{
private const int MaxArgs = 2;
static async Task Main(string[] args)
{
// Parse the command line and show help if necessary
var parsedArgs = CommandLine.Parse(args);
if((parsedArgs.Count == 0) || (parsedArgs.Count > MaxArgs))
{
PrintHelp();
return;
}
// Get the application arguments from the parsed list
string policyName =
CommandLine.GetArgument(parsedArgs, null, "-p", "--policy-name");
string policyFilename =
CommandLine.GetArgument(parsedArgs, null, "-j", "--json-filename");
if( string.IsNullOrEmpty(policyName)
|| (string.IsNullOrEmpty(policyFilename) || !policyFilename.EndsWith(".json")))
CommandLine.ErrorExit(
"\nOne or more of the required arguments is missing or incorrect." +
"\nRun the command with no arguments to see help.");
// Create an IAM service client
var iamClient = new AmazonIdentityManagementServiceClient();
// Create the new policy
var response = await CreateManagedPolicy(iamClient, policyName, policyFilename);
Console.WriteLine($"\nPolicy {response.Policy.PolicyName} has been created.");
Console.WriteLine($" Arn: {response.Policy.Arn}");
}
//
// Method to create an IAM policy from a JSON file
private static async Task CreateManagedPolicy(
IAmazonIdentityManagementService iamClient, string policyName, string jsonFilename)
{
return await iamClient.CreatePolicyAsync(new CreatePolicyRequest{
PolicyName = policyName,
PolicyDocument = File.ReadAllText(jsonFilename)});
}
//
// Command-line help
private static void PrintHelp()
{
Console.WriteLine(
"\nUsage: IamCreatePolicyFromJson -p -j " +
"\n -p, --policy-name: The name you want the new policy to have." +
"\n -j, --json-filename: The name of the JSON file with the policy document.");
}
}
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class that represents a command line on the console or terminal.
// (This is the same for all examples. When you have seen it once, you can ignore it.)
static class CommandLine
{
//
// Method to parse a command line of the form: "--key value" or "-k value".
//
// Parameters:
// - args: The command-line arguments passed into the application by the system.
//
// Returns:
// A Dictionary with string Keys and Values.
//
// If a key is found without a matching value, Dictionary.Value is set to the key
// (including the dashes).
// If a value is found without a matching key, Dictionary.Key is set to "--NoKeyN",
// where "N" represents sequential numbers.
public static Dictionary Parse(string[] args)
{
var parsedArgs = new Dictionary();
int i = 0, n = 0;
while(i < args.Length)
{
// If the first argument in this iteration starts with a dash it's an option.
if(args[i].StartsWith("-"))
{
var key = args[i++];
var value = key;
// Check to see if there's a value that goes with this option?
if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++];
parsedArgs.Add(key, value);
}
// If the first argument in this iteration doesn't start with a dash, it's a value
else
{
parsedArgs.Add("--NoKey" + n.ToString(), args[i++]);
n++;
}
}
return parsedArgs;
}
//
// Method to get an argument from the parsed command-line arguments
//
// Parameters:
// - parsedArgs: The Dictionary object returned from the Parse() method (shown above).
// - defaultValue: The default string to return if the specified key isn't in parsedArgs.
// - keys: An array of keys to look for in parsedArgs.
public static string GetArgument(
Dictionary parsedArgs, string defaultReturn, params string[] keys)
{
string retval = null;
foreach(var key in keys)
if(parsedArgs.TryGetValue(key, out retval)) break;
return retval ?? defaultReturn;
}
//
// Method to exit the application with an error.
public static void ErrorExit(string msg, int code=1)
{
Console.WriteLine("\nError");
Console.WriteLine(msg);
Environment.Exit(code);
}
}
}
```
## Additional considerations
+ The following is an example policy document that you can copy into a JSON file and use as input for this application:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id" : "DotnetTutorialPolicy",
"Statement" : [
{
"Sid" : "DotnetTutorialPolicyS3",
"Effect" : "Allow",
"Action" : [
"s3:Get*",
"s3:List*"
],
"Resource" : "*"
},
{
"Sid" : "DotnetTutorialPolicyPolly",
"Effect": "Allow",
"Action": [
"polly:DescribeVoices",
"polly:SynthesizeSpeech"
],
"Resource": "*"
}
]
}
```
------
+ You can verify that the policy was created by looking in the [IAM console](https://console.aws.amazon.com/iam/home#/policies). In the **Filter policies** drop-down list, select **Customer managed**. Delete the policy when you no longer need it.
+ For more information about policy creation, see [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) and the [IAM JSON policy reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) in the [IAM User Guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/)
# Display the policy document of an IAM managed policy
This example shows you how to use the AWS SDK for .NET to display a policy document. The application creates an IAM client object, finds the default version of the given IAM managed policy, and then displays the policy document in JSON.
The following sections provide snippets of this example. The [complete code for the example](#iam-policies-display-complete-code) is shown after that, and can be built and run as is.
**Topics**
+ [Find the default version](#iam-policies-display-version)
+ [Display the policy document](#iam-policies-display-doc)
+ [Complete code](#iam-policies-display-complete-code)
## Find the default version
The following snippet finds the default version of the given IAM policy.
The example [at the end of this topic](#iam-policies-display-complete-code) shows this snippet in use.
```
//
// Method to determine the default version of an IAM policy
// Returns a string with the version
private static async Task GetDefaultVersion(
IAmazonIdentityManagementService iamClient, string policyArn)
{
// Retrieve all the versions of this policy
string defaultVersion = string.Empty;
ListPolicyVersionsResponse reponseVersions =
await iamClient.ListPolicyVersionsAsync(new ListPolicyVersionsRequest{
PolicyArn = policyArn});
// Find the default version
foreach(PolicyVersion version in reponseVersions.Versions)
{
if(version.IsDefaultVersion)
{
defaultVersion = version.VersionId;
break;
}
}
return defaultVersion;
}
```
## Display the policy document
The following snippet displays the policy document in JSON of the given IAM policy.
The example [at the end of this topic](#iam-policies-display-complete-code) shows this snippet in use.
```
//
// Method to retrieve and display the policy document of an IAM policy
private static async Task ShowPolicyDocument(
IAmazonIdentityManagementService iamClient, string policyArn, string defaultVersion)
{
// Retrieve the policy document of the default version
GetPolicyVersionResponse responsePolicy =
await iamClient.GetPolicyVersionAsync(new GetPolicyVersionRequest{
PolicyArn = policyArn,
VersionId = defaultVersion});
// Display the policy document (in JSON)
Console.WriteLine($"Version {defaultVersion} of the policy (in JSON format):");
Console.WriteLine(
$"{HttpUtility.UrlDecode(responsePolicy.PolicyVersion.Document)}");
}
```
## Complete code
This section shows relevant references and the complete code for this example.
### SDK references
NuGet packages:
+ [AWSSDK.IdentityManagement](https://www.nuget.org/packages/AWSSDK.IdentityManagement)
Programming elements:
+ Namespace [Amazon.IdentityManagement](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IAM/NIAM.html)
Class [AmazonIdentityManagementServiceClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IAM/TIAMServiceClient.html)
+ Namespace [Amazon.IdentityManagement.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IAM/NIAMModel.html)
Class [GetPolicyVersionRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IAM/TGetPolicyVersionRequest.html)
Class [GetPolicyVersionResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IAM/TGetPolicyVersionResponse.html)
Class [ListPolicyVersionsRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IAM/TListPolicyVersionsRequest.html)
Class [ListPolicyVersionsResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IAM/TListPolicyVersionsResponse.html)
Class [PolicyVersion](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/IAM/TPolicyVersion.html)
### The code
```
using System;
using System.Web;
using System.Threading.Tasks;
using Amazon.IdentityManagement;
using Amazon.IdentityManagement.Model;
namespace IamDisplayPolicyJson
{
class Program
{
static async Task Main(string[] args)
{
// Parse the command line and show help if necessary
if(args.Length != 1)
{
Console.WriteLine("\nUsage: IamDisplayPolicyJson policy-arn");
Console.WriteLine(" policy-arn: The ARN of the policy to retrieve.");
return;
}
if(!args[0].StartsWith("arn:"))
{
Console.WriteLine("\nCould not find policy ARN in the command-line arguments:");
Console.WriteLine($"{args[0]}");
return;
}
// Create an IAM service client
var iamClient = new AmazonIdentityManagementServiceClient();
// Retrieve and display the policy document of the given policy
string defaultVersion = await GetDefaultVersion(iamClient, args[0]);
if(string.IsNullOrEmpty(defaultVersion))
Console.WriteLine($"Could not find the default version for policy {args[0]}.");
else
await ShowPolicyDocument(iamClient, args[0], defaultVersion);
}
//
// Method to determine the default version of an IAM policy
// Returns a string with the version
private static async Task GetDefaultVersion(
IAmazonIdentityManagementService iamClient, string policyArn)
{
// Retrieve all the versions of this policy
string defaultVersion = string.Empty;
ListPolicyVersionsResponse reponseVersions =
await iamClient.ListPolicyVersionsAsync(new ListPolicyVersionsRequest{
PolicyArn = policyArn});
// Find the default version
foreach(PolicyVersion version in reponseVersions.Versions)
{
if(version.IsDefaultVersion)
{
defaultVersion = version.VersionId;
break;
}
}
return defaultVersion;
}
//
// Method to retrieve and display the policy document of an IAM policy
private static async Task ShowPolicyDocument(
IAmazonIdentityManagementService iamClient, string policyArn, string defaultVersion)
{
// Retrieve the policy document of the default version
GetPolicyVersionResponse responsePolicy =
await iamClient.GetPolicyVersionAsync(new GetPolicyVersionRequest{
PolicyArn = policyArn,
VersionId = defaultVersion});
// Display the policy document (in JSON)
Console.WriteLine($"Version {defaultVersion} of the policy (in JSON format):");
Console.WriteLine(
$"{HttpUtility.UrlDecode(responsePolicy.PolicyVersion.Document)}");
}
}
}
```
# Granting access by using an IAM role
This tutorial shows you how to use the AWS SDK for .NET to enable IAM roles on Amazon EC2 instances.
## Overview
All requests to AWS must be cryptographically signed by using credentials issued by AWS. Therefore, you need a strategy to manage credentials for applications that run on Amazon EC2 instances. You have to distribute, store, and rotate these credentials securely, but also keep them accessible to the applications.
With IAM roles, you can effectively manage these credentials. You create an IAM role and configure it with the permissions that an application requires, and then attach that role to an EC2 instance. To read more about the benefits of using IAM roles, see [IAM roles for Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/). Also see the information about [IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the IAM User Guide.
For an application that is built using the AWS SDK for .NET, when the application constructs a client object for an AWS service, the object searches for credentials from several potential sources. The order in which it searches is shown in [Credential and profile resolution](creds-assign.md).
If the client object doesn't find credentials from any other source, it retrieves temporary credentials that have the same permissions as those that have been configured into the IAM role and are in the metadata of the EC2 instance. These credentials are used to make calls to AWS from the client object.
## About this tutorial
As you follow this tutorial, you use the AWS SDK for .NET (and other tools) to launch an Amazon EC2 instance with an IAM role attached, and then see an application on the instance using the permissions of the IAM role.
**Topics**
+ [Overview](#hosm-overview)
+ [About this tutorial](#about-hosm-tutorial)
+ [Create a sample Amazon S3 application](#net-dg-hosm-sample-s3-app)
+ [Create an IAM role](#net-dg-hosm-create-the-role)
+ [Launch an EC2 instance and attach the IAM role](#net-dg-hosm-launch-ec2-instance)
+ [Connect to the EC2 instance](#net-dg-hosm-connect)
+ [Run the sample application on the EC2 instance](#net-dg-hosm-run-the-app)
+ [Clean up](#net-dg-hosm-cleanup)
## Create a sample Amazon S3 application
This sample application retrieves an object from Amazon S3. To run the application, you need the following:
+ An Amazon S3 bucket that contains a text file.
+ AWS credentials on your development machine that allow you to access to the bucket.
For information about creating an Amazon S3 bucket and uploading an object, see the [Amazon Simple Storage Service User Guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/). For information about AWS credentials, see [Configure SDK authentication with AWS](creds-idc.md).
Create a .NET Core project with the following code. Then test the application on your development machine.
**Note**
On your development machine, the .NET Core Runtime is installed, which enables you to run the application without publishing it. When you create an EC2 instance later in this tutorial, you can choose to install the .NET Core Runtime on the instance. This gives you a similar experience and a smaller file transfer.
However, you can also choose not to install the .NET Core Runtime on the instance. If you choose this course of action, you must publish the application so that all dependencies are included when you transfer it to the instance.
### SDK references
NuGet packages:
+ [AWSSDK.S3](https://www.nuget.org/packages/AWSSDK.S3)
Programming elements:
+ Namespace [Amazon.S3](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/NS3.html)
Class [AmazonS3Client](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/TS3Client.html)
+ Namespace [Amazon.S3.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/NS3Model.html)
Class [GetObjectResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/TGetObjectResponse.html)
### The code
```
using System;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;
using Amazon.S3;
using Amazon.S3.Model;
namespace S3GetTextItem
{
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class to retrieve a text file from an S3 bucket and write it to a local file
class Program
{
static async Task Main(string[] args)
{
// Parse the command line and show help if necessary
var parsedArgs = CommandLine.Parse(args);
if(parsedArgs.Count == 0)
{
PrintHelp();
return;
}
// Get the application arguments from the parsed list
string bucket =
CommandLine.GetArgument(parsedArgs, null, "-b", "--bucket-name");
string item =
CommandLine.GetArgument(parsedArgs, null, "-t", "--text-object");
string outFile =
CommandLine.GetArgument(parsedArgs, null, "-o", "--output-filename");
if( string.IsNullOrEmpty(bucket)
|| string.IsNullOrEmpty(item)
|| string.IsNullOrEmpty(outFile))
CommandLine.ErrorExit(
"\nOne or more of the required arguments is missing or incorrect." +
"\nRun the command with no arguments to see help.");
// Create the S3 client object and get the file object from the bucket.
var response = await GetObject(new AmazonS3Client(), bucket, item);
// Write the contents of the file object to the given output file.
var reader = new StreamReader(response.ResponseStream);
string contents = reader.ReadToEnd();
using (var s = new FileStream(outFile, FileMode.Create))
using (var writer = new StreamWriter(s))
writer.WriteLine(contents);
}
//
// Method to get an object from an S3 bucket.
private static async Task GetObject(
IAmazonS3 s3Client, string bucket, string item)
{
Console.WriteLine($"Retrieving {item} from bucket {bucket}.");
return await s3Client.GetObjectAsync(bucket, item);
}
//
// Command-line help
private static void PrintHelp()
{
Console.WriteLine(
"\nUsage: S3GetTextItem -b -t -o " +
"\n -b, --bucket-name: The name of the S3 bucket." +
"\n -t, --text-object: The name of the text object in the bucket." +
"\n -o, --output-filename: The name of the file to write the text to.");
}
}
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class that represents a command line on the console or terminal.
// (This is the same for all examples. When you have seen it once, you can ignore it.)
static class CommandLine
{
//
// Method to parse a command line of the form: "--key value" or "-k value".
//
// Parameters:
// - args: The command-line arguments passed into the application by the system.
//
// Returns:
// A Dictionary with string Keys and Values.
//
// If a key is found without a matching value, Dictionary.Value is set to the key
// (including the dashes).
// If a value is found without a matching key, Dictionary.Key is set to "--NoKeyN",
// where "N" represents sequential numbers.
public static Dictionary Parse(string[] args)
{
var parsedArgs = new Dictionary();
int i = 0, n = 0;
while(i < args.Length)
{
// If the first argument in this iteration starts with a dash it's an option.
if(args[i].StartsWith("-"))
{
var key = args[i++];
var value = key;
// Check to see if there's a value that goes with this option?
if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++];
parsedArgs.Add(key, value);
}
// If the first argument in this iteration doesn't start with a dash, it's a value
else
{
parsedArgs.Add("--NoKey" + n.ToString(), args[i++]);
n++;
}
}
return parsedArgs;
}
//
// Method to get an argument from the parsed command-line arguments
//
// Parameters:
// - parsedArgs: The Dictionary object returned from the Parse() method (shown above).
// - defaultValue: The default string to return if the specified key isn't in parsedArgs.
// - keys: An array of keys to look for in parsedArgs.
public static string GetArgument(
Dictionary parsedArgs, string defaultReturn, params string[] keys)
{
string retval = null;
foreach(var key in keys)
if(parsedArgs.TryGetValue(key, out retval)) break;
return retval ?? defaultReturn;
}
//
// Method to exit the application with an error.
public static void ErrorExit(string msg, int code=1)
{
Console.WriteLine("\nError");
Console.WriteLine(msg);
Environment.Exit(code);
}
}
}
```
If you want, you can temporarily remove the credentials you use on your development machine to see how the application responds. (But be sure to restore the credentials when you're finished.)
## Create an IAM role
Create an IAM role that has the appropriate permissions to access Amazon S3.
1. Open the [IAM console](https://console.aws.amazon.com/iam/).
1. In the navigation pane, choose **Roles**, and then choose **Create Role**.
1. Select **AWS service**, find and choose **EC2**, and choose **Next: Permissions**.
1. Under **Attach permissions policies**, find and select **AmazonS3ReadOnlyAccess**. Review the policy if you want to, and then choose **Next: Tags**.
1. Add tags if you want and then choose **Next: Review**.
1. Type a name and description for the role, and then choose **Create role**. Remember this name because you'll need it when you launch your EC2 instance.
## Launch an EC2 instance and attach the IAM role
Launch an EC2 instance with the IAM role you created previously. You can do so in the following ways.
+ **Using the EC2 console**
To launch an instance by using the EC2 console, see [Launch an instance using the new launch instance wizard](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-launch-instance-wizard.html) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/).
As you look through the launch page, you should at least expand the **Advanced details** pane so that you can specify the IAM role you created earlier in **IAM instance profile**.
+ **Using the AWS SDK for .NET**
For information about this, see [Launching an Amazon EC2 instance](run-instance.md), including the [Additional considerations](run-instance.md#run-instance-additional) near the end of that topic.
To launch an EC2 instance that has an IAM role attached, an IAM user's configuration must include certain permissions. For more information about the required permissions, see [Grant a user permission to pass an IAM role to an instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#permission-to-pass-iam-roles) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/).
## Connect to the EC2 instance
Connect to the EC2 instance so that you can transfer the sample application to it and then run the application. You'll need the file that contains the private portion of the key pair you used to launch the instance; that is, the PEM file.
For information about connecting to an instance, see [Connect to your Linux instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-to-linux-instance.html) or [Connect to your Windows instance](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/connecting_to_windows_instance.html) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/). When you connect, do so in such a way that you can transfer files from your development machine to your instance.
If you're using Visual Studio on Windows, you can also connect to the instance by using the Toolkit for Visual Studio. For more information, see [Connecting to an Amazon EC2 Instance](https://docs.aws.amazon.com/toolkit-for-visual-studio/latest/user-guide/tkv-ec2-ami.html#connect-ec2) in the AWS Toolkit for Visual Studio User Guide.
## Run the sample application on the EC2 instance
1. Copy the application files from your local drive to your instance.
Which files you transfer depends on how you built the application and whether your instance has the .NET Core Runtime installed. For information about how to transfer files to your instance, see [Connect to your Linux instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-to-linux-instance.html) (see the appropriate sub-section) or [Transfer files to Windows instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-to-linux-instanceWindowsFileTransfer.html) in the [Amazon EC2 User Guide](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/).
1. Start the application and verify that it runs with the same results as on your development machine.
1. Verify that the application uses the credentials provided by the IAM role.
1. Open the [Amazon EC2 console](https://console.aws.amazon.com/ec2/).
1. Select the instance and detach the IAM role through **Actions**, **Instance Settings**, **Attach/Replace IAM Role**.
1. Run the application again and see that it returns an authorization error.
## Clean up
When you are finished with this tutorial, and if you no longer want the EC2 instance you created, be sure to terminate the instance to avoid unwanted cost. You can do so in the [Amazon EC2 console](https://console.aws.amazon.com/ec2/) or programmatically, as described in [Terminating an Amazon EC2 instance](terminate-instance.md). If you want to, you can also delete other resources that you created for this tutorial. These might include an IAM role, an EC2 keypair and PEM file, a security group, etc.
# Using Amazon Simple Storage Service Internet storage
The AWS SDK for .NET supports [Amazon S3](https://aws.amazon.com/s3/), which is storage for the Internet. It is designed to make web-scale computing easier for developers.
## APIs
The AWS SDK for .NET provides APIs for Amazon S3 clients. The APIs enable you to work with Amazon S3 resources such as buckets and items. To view the full set of APIs for Amazon S3, see the following:
+ [AWS SDK for .NET API Reference](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/) (and scroll to "Amazon.S3").
+ [Amazon.Extensions.S3.Encryption](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.html) documentation
The Amazon S3 APIs are provided by the following NuGet packages:
+ [AWSSDK.S3](https://www.nuget.org/packages/AWSSDK.S3)
+ [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption)
## Prerequisites
Before you begin, be sure you have [set up your environment and project](net-dg-config.md). Also review the information in [SDK features](net-dg-sdk-features.md).
## Examples in this document
The following topics in this document show you how to use the AWS SDK for .NET to work with Amazon S3.
+ [Using KMS keys for S3 encryption](kms-keys-s3-encryption.md)
## Examples in other documents
The following links to the [Amazon S3 Developer Guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/) provide additional examples of how to use the AWS SDK for .NET to work with Amazon S3.
**Note**
Although these examples and additional programming considerations were created for Version 3 of the AWS SDK for .NET using .NET Framework, they are also viable for later versions of the AWS SDK for .NET using .NET Core. Small adjustments in the code are sometimes necessary.
**Amazon S3 programming examples**
+ [Managing ACLs](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-using-dot-net-sdk.html)
+ [Creating a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/dev/create-bucket-get-location-example.html#create-bucket-get-location-dotnet)
+ [Upload an Object](https://docs.aws.amazon.com/AmazonS3/latest/dev/UploadObjSingleOpNET.html)
+ [Multipart Upload with the High-Level API ([Amazon.S3.Transfer.TransferUtility](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/TTransferUtility.html))](https://docs.aws.amazon.com/AmazonS3/latest/dev/usingHLmpuDotNet.html)
+ [Multipart Upload with the Low-Level API](https://docs.aws.amazon.com/AmazonS3/latest/dev/usingLLmpuDotNet.html)
+ [Listing Objects](https://docs.aws.amazon.com/AmazonS3/latest/dev/list-obj-version-enabled-bucket.html#list-obj-version-enabled-bucket-sdk-examples)
+ [Listing Keys](https://docs.aws.amazon.com/AmazonS3/latest/dev/ListingObjectKeysUsingNetSDK.html)
+ [Get an Object](https://docs.aws.amazon.com/AmazonS3/latest/dev/RetrievingObjectUsingNetSDK.html)
+ [Copy an Object](https://docs.aws.amazon.com/AmazonS3/latest/dev/CopyingObjectUsingNetSDK.html)
+ [Copy an Object with the Multipart Upload API](https://docs.aws.amazon.com/AmazonS3/latest/dev/CopyingObjctsUsingLLNetMPUapi.html)
+ [Deleting an Object](https://docs.aws.amazon.com/AmazonS3/latest/dev/DeletingOneObjectUsingNetSDK.html)
+ [Deleting Multiple Objects](https://docs.aws.amazon.com/AmazonS3/latest/dev/DeletingMultipleObjectsUsingNetSDK.html)
+ [Restore an Object](https://docs.aws.amazon.com/AmazonS3/latest/dev/restore-object-dotnet.html)
+ [Configure a Bucket for Notifications](https://docs.aws.amazon.com/AmazonS3/latest/dev/ways-to-add-notification-config-to-bucket.html)
+ [Manage an Object’s Lifecycle](https://docs.aws.amazon.com/AmazonS3/latest/dev/manage-lifecycle-using-dot-net.html)
+ [Generate a Pre-signed Object URL](https://docs.aws.amazon.com/AmazonS3/latest/dev/ShareObjectPreSignedURLDotNetSDK.html)
+ [Managing Websites](https://docs.aws.amazon.com/AmazonS3/latest/dev/ConfigWebSiteDotNet.html)
+ [Enabling Cross-Origin Resource Sharing (CORS)](https://docs.aws.amazon.com/AmazonS3/latest/dev/ManageCorsUsingDotNet.html)
**Additional programming considerations**
+ [Using the AWS SDK for .NET for Amazon S3 Programming](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingTheMPDotNetAPI.html)
+ [Making Requests Using IAM User Temporary Credentials](https://docs.aws.amazon.com/AmazonS3/latest/dev/AuthUsingTempSessionTokenDotNet.html)
+ [Making Requests Using Federated User Temporary Credentials](https://docs.aws.amazon.com/AmazonS3/latest/dev/AuthUsingTempFederationTokenDotNet.html)
+ [Specifying Server-Side Encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/SSEUsingDotNetSDK.html)
+ [Specifying Server-Side Encryption with Customer-Provided Encryption Keys](https://docs.aws.amazon.com/AmazonS3/latest/dev/sse-c-using-dot-net-sdk.html)
# Using AWS KMS keys for Amazon S3 encryption in the AWS SDK for .NET
This example shows you how to use AWS Key Management Service keys to encrypt Amazon S3 objects. The application creates a customer master key (CMK) and uses it to create an [AmazonS3EncryptionClientV2](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.AmazonS3EncryptionClientV2.html) object for client-side encryption. The application uses that client to create an encrypted object from a given text file in an existing Amazon S3 bucket. It then decrypts the object and displays its contents.
**Warning**
A similar class called `AmazonS3EncryptionClient` is deprecated and is less secure than the `AmazonS3EncryptionClientV2` class. To migrate existing code that uses `AmazonS3EncryptionClient`, see [S3 Encryption Client Migration (V1 to V2)](s3-encryption-migration-v1-v2.md).
**Topics**
+ [Create encryption materials](#kms-s3-enc-mat)
+ [Create and encrypt an Amazon S3 object](#kms-s3-create-ojbect)
+ [Complete code](#kms-s3-complete-code)
+ [Additional considerations](#kms-s3-additional)
## Create encryption materials
The following snippet creates an `EncryptionMaterials` object that contains a KMS key ID.
The example [at the end of this topic](#kms-s3-complete-code) shows this snippet in use.
```
// Create a customer master key (CMK) and store the result
CreateKeyResponse createKeyResponse =
await new AmazonKeyManagementServiceClient().CreateKeyAsync(new CreateKeyRequest());
var kmsEncryptionContext = new Dictionary();
var kmsEncryptionMaterials = new EncryptionMaterialsV2(
createKeyResponse.KeyMetadata.KeyId, KmsType.KmsContext, kmsEncryptionContext);
```
## Create and encrypt an Amazon S3 object
The following snippet creates an `AmazonS3EncryptionClientV2` object that uses the encryption materials created earlier. It then uses the client to create and encrypt a new Amazon S3 object.
The example [at the end of this topic](#kms-s3-complete-code) shows this snippet in use.
```
//
// Method to create and encrypt an object in an S3 bucket
static async Task CreateAndRetrieveObjectAsync(
EncryptionMaterialsV2 materials, string bucketName,
string fileName, string itemName)
{
// CryptoStorageMode.ObjectMetadata is required for KMS EncryptionMaterials
var config = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy)
{
StorageMode = CryptoStorageMode.ObjectMetadata
};
var s3EncClient = new AmazonS3EncryptionClientV2(config, materials);
// Create, encrypt, and put the object
await s3EncClient.PutObjectAsync(new PutObjectRequest
{
BucketName = bucketName,
Key = itemName,
ContentBody = File.ReadAllText(fileName)
});
// Get, decrypt, and return the object
return await s3EncClient.GetObjectAsync(new GetObjectRequest
{
BucketName = bucketName,
Key = itemName
});
}
```
## Complete code
This section shows relevant references and the complete code for this example.
### SDK references
NuGet packages:
+ [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption)
Programming elements:
+ Namespace [Amazon.Extensions.S3.Encryption](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.html)
Class [AmazonS3EncryptionClientV2](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.AmazonS3EncryptionClientV2.html)
Class [AmazonS3CryptoConfigurationV2](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.AmazonS3CryptoConfigurationV2.html)
Class [CryptoStorageMode](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.CryptoStorageMode.html)
Class [EncryptionMaterialsV2](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.EncryptionMaterialsV2.html)
+ Namespace [Amazon.Extensions.S3.Encryption.Primitives](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.Primitives.html)
Class [KmsType](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.Primitives.KmsType.html)
+ Namespace [Amazon.S3.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/NS3Model.html)
Class [GetObjectRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/TGetObjectRequest.html)
Class [GetObjectResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/TGetObjectResponse.html)
Class [PutObjectRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/TPutObjectRequest.html)
+ Namespace [Amazon.KeyManagementService](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/KeyManagementService/NKeyManagementService.html)
Class [AmazonKeyManagementServiceClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/KeyManagementService/TKeyManagementServiceClient.html)
+ Namespace [Amazon.KeyManagementService.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/KeyManagementService/NKeyManagementServiceModel.html)
Class [CreateKeyRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/KeyManagementService/TCreateKeyRequest.html)
Class [CreateKeyResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/KeyManagementService/TCreateKeyResponse.html)
### The code
```
using System;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;
using Amazon.KeyManagementService;
using Amazon.KeyManagementService.Model;
namespace KmsS3Encryption
{
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class to store text in an encrypted S3 object.
class Program
{
private const int MaxArgs = 3;
public static async Task Main(string[] args)
{
// Parse the command line and show help if necessary
var parsedArgs = CommandLine.Parse(args);
if((parsedArgs.Count == 0) || (parsedArgs.Count > MaxArgs))
{
PrintHelp();
return;
}
// Get the application arguments from the parsed list
string bucketName =
CommandLine.GetArgument(parsedArgs, null, "-b", "--bucket-name");
string fileName =
CommandLine.GetArgument(parsedArgs, null, "-f", "--file-name");
string itemName =
CommandLine.GetArgument(parsedArgs, null, "-i", "--item-name");
if(string.IsNullOrEmpty(bucketName) || (string.IsNullOrEmpty(fileName)))
CommandLine.ErrorExit(
"\nOne or more of the required arguments is missing or incorrect." +
"\nRun the command with no arguments to see help.");
if(!File.Exists(fileName))
CommandLine.ErrorExit($"\nThe given file {fileName} doesn't exist.");
if(string.IsNullOrEmpty(itemName))
itemName = Path.GetFileName(fileName);
// Create a customer master key (CMK) and store the result
CreateKeyResponse createKeyResponse =
await new AmazonKeyManagementServiceClient().CreateKeyAsync(new CreateKeyRequest());
var kmsEncryptionContext = new Dictionary();
var kmsEncryptionMaterials = new EncryptionMaterialsV2(
createKeyResponse.KeyMetadata.KeyId, KmsType.KmsContext, kmsEncryptionContext);
// Create the object in the bucket, then display the content of the object
var putObjectResponse =
await CreateAndRetrieveObjectAsync(kmsEncryptionMaterials, bucketName, fileName, itemName);
Stream stream = putObjectResponse.ResponseStream;
StreamReader reader = new StreamReader(stream);
Console.WriteLine(reader.ReadToEnd());
}
//
// Method to create and encrypt an object in an S3 bucket
static async Task CreateAndRetrieveObjectAsync(
EncryptionMaterialsV2 materials, string bucketName,
string fileName, string itemName)
{
// CryptoStorageMode.ObjectMetadata is required for KMS EncryptionMaterials
var config = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2AndLegacy)
{
StorageMode = CryptoStorageMode.ObjectMetadata
};
var s3EncClient = new AmazonS3EncryptionClientV2(config, materials);
// Create, encrypt, and put the object
await s3EncClient.PutObjectAsync(new PutObjectRequest
{
BucketName = bucketName,
Key = itemName,
ContentBody = File.ReadAllText(fileName)
});
// Get, decrypt, and return the object
return await s3EncClient.GetObjectAsync(new GetObjectRequest
{
BucketName = bucketName,
Key = itemName
});
}
//
// Command-line help
private static void PrintHelp()
{
Console.WriteLine(
"\nUsage: KmsS3Encryption -b -f [-i ]" +
"\n -b, --bucket-name: The name of an existing S3 bucket." +
"\n -f, --file-name: The name of a text file with content to encrypt and store in S3." +
"\n -i, --item-name: The name you want to use for the item." +
"\n If item-name isn't given, file-name will be used.");
}
}
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class that represents a command line on the console or terminal.
// (This is the same for all examples. When you have seen it once, you can ignore it.)
static class CommandLine
{
//
// Method to parse a command line of the form: "--key value" or "-k value".
//
// Parameters:
// - args: The command-line arguments passed into the application by the system.
//
// Returns:
// A Dictionary with string Keys and Values.
//
// If a key is found without a matching value, Dictionary.Value is set to the key
// (including the dashes).
// If a value is found without a matching key, Dictionary.Key is set to "--NoKeyN",
// where "N" represents sequential numbers.
public static Dictionary Parse(string[] args)
{
var parsedArgs = new Dictionary();
int i = 0, n = 0;
while(i < args.Length)
{
// If the first argument in this iteration starts with a dash it's an option.
if(args[i].StartsWith("-"))
{
var key = args[i++];
var value = key;
// Check to see if there's a value that goes with this option?
if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++];
parsedArgs.Add(key, value);
}
// If the first argument in this iteration doesn't start with a dash, it's a value
else
{
parsedArgs.Add("--NoKey" + n.ToString(), args[i++]);
n++;
}
}
return parsedArgs;
}
//
// Method to get an argument from the parsed command-line arguments
//
// Parameters:
// - parsedArgs: The Dictionary object returned from the Parse() method (shown above).
// - defaultValue: The default string to return if the specified key isn't in parsedArgs.
// - keys: An array of keys to look for in parsedArgs.
public static string GetArgument(
Dictionary parsedArgs, string defaultReturn, params string[] keys)
{
string retval = null;
foreach(var key in keys)
if(parsedArgs.TryGetValue(key, out retval)) break;
return retval ?? defaultReturn;
}
//
// Method to exit the application with an error.
public static void ErrorExit(string msg, int code=1)
{
Console.WriteLine("\nError");
Console.WriteLine(msg);
Environment.Exit(code);
}
}
}
```
## Additional considerations
+ You can check the results of this example. To do so, go to the [Amazon S3 console](https://console.aws.amazon.com/s3) and open the bucket you provided to the application. Then find the new object, download it, and open it in a text editor.
+ The [AmazonS3EncryptionClientV2](https://aws.github.io/amazon-s3-encryption-client-dotnet/api/Amazon.Extensions.S3.Encryption.AmazonS3EncryptionClientV2.html) class implements the same interface as the standard `AmazonS3Client` class. This makes it easier to port your code to the `AmazonS3EncryptionClientV2` class so that encryption and decryption happen automatically and transparently in the client.
+ One advantage of using an AWS KMS key as your master key is that you don't need to store and manage your own master keys; this is done by AWS. A second advantage is that the `AmazonS3EncryptionClientV2` class of the AWS SDK for .NET is interoperable with the `AmazonS3EncryptionClientV2` class of the AWS SDK for Java. This means you can encrypt with the AWS SDK for Java and decrypt with the AWS SDK for .NET, and vice versa.
**Note**
The `AmazonS3EncryptionClientV2` class of the AWS SDK for .NET supports KMS master keys only when run in metadata mode. The instruction file mode of the `AmazonS3EncryptionClientV2` class of the AWS SDK for .NET is incompatible with the `AmazonS3EncryptionClientV2` class of the AWS SDK for Java.
+ For more information about client-side encryption with the `AmazonS3EncryptionClientV2` class, and how envelope encryption works, see [Client Side Data Encryption with AWS SDK for .NET and Amazon S3](https://aws.amazon.com/blogs/developer/client-side-data-encryption-with-aws-sdk-for-net-and-amazon-s3/).
# Sending Notifications From the Cloud Using Amazon Simple Notification Service
**Note**
The information in this topic is specific to projects based on .NET Framework and the AWS SDK for .NET version 3.3 and earlier.
The AWS SDK for .NET supports Amazon Simple Notification Service (Amazon SNS), which is a web service that enables applications, end users, and devices to instantly send notifications from the cloud. For more information, see [Amazon SNS](https://aws.amazon.com/sns/).
## Listing Your Amazon SNS Topics
The following example shows how to list your Amazon SNS topics, the subscriptions to each topic, and the attributes for each topic. This example uses the default [AmazonSimpleNotificationServiceClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SNS/TSNSClient.html).
```
// using Amazon.SimpleNotificationService;
// using Amazon.SimpleNotificationService.Model;
var client = new AmazonSimpleNotificationServiceClient();
var request = new ListTopicsRequest();
var response = new ListTopicsResponse();
do
{
response = client.ListTopics(request);
foreach (var topic in response.Topics)
{
Console.WriteLine("Topic: {0}", topic.TopicArn);
var subs = client.ListSubscriptionsByTopic(
new ListSubscriptionsByTopicRequest
{
TopicArn = topic.TopicArn
});
var ss = subs.Subscriptions;
if (ss.Any())
{
Console.WriteLine(" Subscriptions:");
foreach (var sub in ss)
{
Console.WriteLine(" {0}", sub.SubscriptionArn);
}
}
var attrs = client.GetTopicAttributes(
new GetTopicAttributesRequest
{
TopicArn = topic.TopicArn
}).Attributes;
if (attrs.Any())
{
Console.WriteLine(" Attributes:");
foreach (var attr in attrs)
{
Console.WriteLine(" {0} = {1}", attr.Key, attr.Value);
}
}
Console.WriteLine();
}
request.NextToken = response.NextToken;
} while (!string.IsNullOrEmpty(response.NextToken));
```
## Sending a Message to an Amazon SNS Topic
The following example shows how to send a message to an Amazon SNS topic. The example takes one argument, the ARN of the Amazon SNS topic.
```
using System;
using System.Linq;
using System.Threading.Tasks;
using Amazon;
using Amazon.SimpleNotificationService;
using Amazon.SimpleNotificationService.Model;
namespace SnsSendMessage
{
class Program
{
static void Main(string[] args)
{
/* Topic ARNs must be in the correct format:
* arn:aws:sns:REGION:ACCOUNT_ID:NAME
*
* where:
* REGION is the region in which the topic is created, such as us-west-2
* ACCOUNT_ID is your (typically) 12-character account ID
* NAME is the name of the topic
*/
string topicArn = args[0];
string message = "Hello at " + DateTime.Now.ToShortTimeString();
var client = new AmazonSimpleNotificationServiceClient(region: Amazon.RegionEndpoint.USWest2);
var request = new PublishRequest
{
Message = message,
TopicArn = topicArn
};
try
{
var response = client.Publish(request);
Console.WriteLine("Message sent to topic:");
Console.WriteLine(message);
}
catch (Exception ex)
{
Console.WriteLine("Caught exception publishing request:");
Console.WriteLine(ex.Message);
}
}
}
}
```
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/.dotnet/example_code_legacy/SNS/SnsSendMessage.cs), including information on how to build and run the example from the command line, on GitHub.
## Sending an SMS Message to a Phone Number
The following example shows how to send an SMS message to a telephone number. The example takes one argument, the telephone number, which must be in either of the two formats described in the comments.
```
using System;
using System.Linq;
using System.Threading.Tasks;
using Amazon;
using Amazon.SimpleNotificationService;
using Amazon.SimpleNotificationService.Model;
namespace SnsPublish
{
class Program
{
static void Main(string[] args)
{
// US phone numbers must be in the correct format:
// +1 (nnn) nnn-nnnn OR +1nnnnnnnnnn
string number = args[0];
string message = "Hello at " + DateTime.Now.ToShortTimeString();
var client = new AmazonSimpleNotificationServiceClient(region: Amazon.RegionEndpoint.USWest2);
var request = new PublishRequest
{
Message = message,
PhoneNumber = number
};
try
{
var response = client.Publish(request);
Console.WriteLine("Message sent to " + number + ":");
Console.WriteLine(message);
}
catch (Exception ex)
{
Console.WriteLine("Caught exception publishing request:");
Console.WriteLine(ex.Message);
}
}
}
}
```
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/.dotnet/example_code_legacy/SNS/SnsPublish.cs), including information on how to build and run the example from the command line, on GitHub.
# Messaging using Amazon SQS
The AWS SDK for .NET supports [Amazon Simple Queue Service (Amazon SQS)](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/), which is a message queuing service that handles messages or workflows between components in a system.
Amazon SQS queues provide a mechanism that enables you to send, store, and receive messages between software components such as microservices, distributed systems, and serverless applications. This enables you to decouple such components and frees you from the need to design and operate your own messaging system. For information about how queues and messages work in Amazon SQS, see [Amazon SQS tutorials](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-other-tutorials.html) and [Basic Amazon SQS architecture](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-basic-architecture.html) in the [Amazon Simple Queue Service Developer Guide](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/).
**Important**
Due to the distributed nature of queues, Amazon SQS can't guarantee that you'll receive messages in the precise order they're sent. If you need to preserve message order, use an [Amazon SQS FIFO queue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-fifo-queues.html).
## APIs
The AWS SDK for .NET provides APIs for Amazon SQS clients. The APIs enable you to work with Amazon SQS features such as queues and messages. This section contains a small number of examples that show you the patterns you can follow when working with these APIs. To view the full set of APIs, see the [AWS SDK for .NET API Reference](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/) (and scroll to "Amazon.SQS").
The Amazon SQS APIs are provided by the [AWSSDK.SQS](https://www.nuget.org/packages/AWSSDK.SQS) NuGet package.
## Prerequisites
Before you begin, be sure you have [set up your environment and project](net-dg-config.md). Also review the information in [SDK features](net-dg-sdk-features.md).
## Topics
**Topics**
+ [APIs](#w2aac19c15c25b9)
+ [Prerequisites](#w2aac19c15c25c11)
+ [Topics](#w2aac19c15c25c13)
+ [Creating queues](CreateQueue.md)
+ [Updating queues](UpdateSqsQueue.md)
+ [Deleting queues](DeleteSqsQueue.md)
+ [Sending messages](SendMessage.md)
+ [Receiving messages](ReceiveMessage.md)
# Creating Amazon SQS queues
This example shows you how to use the AWS SDK for .NET to create an Amazon SQS queue. The application creates a [dead-letter queue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html) if you don't supply the ARN for one. It then creates a standard message queue, which includes a dead-letter queue (the one you supplied or the one that was created).
If you don't supply any command-line arguments, the application simply shows information about all existing queues.
The following sections provide snippets of this example. The [complete code for the example](#CreateQueue-complete-code) is shown after that, and can be built and run as is.
**Topics**
+ [Show existing queues](#CreateQueue-show-queues)
+ [Create the queue](#CreateQueue-create-queue)
+ [Get a queue's ARN](#CreateQueue-get-arn)
+ [Complete code](#CreateQueue-complete-code)
+ [Additional considerations](#CreateQueue-additional)
## Show existing queues
The following snippet shows a list of the existing queues in the SQS client's region and the attributes of each queue.
The example [at the end of this topic](#CreateQueue-complete-code) shows this snippet in use.
```
//
// Method to show a list of the existing queues
private static async Task ShowQueues(IAmazonSQS sqsClient)
{
ListQueuesResponse responseList = await sqsClient.ListQueuesAsync("");
Console.WriteLine();
foreach(string qUrl in responseList.QueueUrls)
{
// Get and show all attributes. Could also get a subset.
await ShowAllAttributes(sqsClient, qUrl);
}
}
//
// Method to show all attributes of a queue
private static async Task ShowAllAttributes(IAmazonSQS sqsClient, string qUrl)
{
var attributes = new List{ QueueAttributeName.All };
GetQueueAttributesResponse responseGetAtt =
await sqsClient.GetQueueAttributesAsync(qUrl, attributes);
Console.WriteLine($"Queue: {qUrl}");
foreach(var att in responseGetAtt.Attributes)
Console.WriteLine($"\t{att.Key}: {att.Value}");
}
```
## Create the queue
The following snippet creates a queue. The snippet includes the use of a dead-letter queue, but a dead-letter queue isn't necessarily required for your queues.
The example [at the end of this topic](#CreateQueue-complete-code) shows this snippet in use.
```
//
// Method to create a queue. Returns the queue URL.
private static async Task CreateQueue(
IAmazonSQS sqsClient, string qName, string deadLetterQueueUrl=null,
string maxReceiveCount=null, string receiveWaitTime=null)
{
var attrs = new Dictionary();
// If a dead-letter queue is given, create a message queue
if(!string.IsNullOrEmpty(deadLetterQueueUrl))
{
attrs.Add(QueueAttributeName.ReceiveMessageWaitTimeSeconds, receiveWaitTime);
attrs.Add(QueueAttributeName.RedrivePolicy,
$"{{\"deadLetterTargetArn\":\"{await GetQueueArn(sqsClient, deadLetterQueueUrl)}\"," +
$"\"maxReceiveCount\":\"{maxReceiveCount}\"}}");
// Add other attributes for the message queue such as VisibilityTimeout
}
// If no dead-letter queue is given, create one of those instead
//else
//{
// // Add attributes for the dead-letter queue as needed
// attrs.Add();
//}
// Create the queue
CreateQueueResponse responseCreate = await sqsClient.CreateQueueAsync(
new CreateQueueRequest{QueueName = qName, Attributes = attrs});
return responseCreate.QueueUrl;
}
```
## Get a queue's ARN
The following snippet gets the ARN of the queue identified by the given queue URL.
The example [at the end of this topic](#CreateQueue-complete-code) shows this snippet in use.
```
//
// Method to get the ARN of a queue
private static async Task GetQueueArn(IAmazonSQS sqsClient, string qUrl)
{
GetQueueAttributesResponse responseGetAtt = await sqsClient.GetQueueAttributesAsync(
qUrl, new List{QueueAttributeName.QueueArn});
return responseGetAtt.QueueARN;
}
```
## Complete code
This section shows relevant references and the complete code for this example.
### SDK references
NuGet packages:
+ [AWSSDK.SQS](https://www.nuget.org/packages/AWSSDK.SQS)
Programming elements:
+ Namespace [Amazon.SQS](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/NSQS.html)
Class [AmazonSQSClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TSQSClient.html)
Class [QueueAttributeName](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TQueueAttributeName.html)
+ Namespace [Amazon.SQS.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/NSQSModel.html)
Class [CreateQueueRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TCreateQueueRequest.html)
Class [CreateQueueResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TCreateQueueResponse.html)
Class [GetQueueAttributesResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TGetQueueAttributesResponse.html)
Class [ListQueuesResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TListQueuesResponse.html)
### The code
```
using System;
using System.Threading.Tasks;
using System.Collections.Generic;
using Amazon.SQS;
using Amazon.SQS.Model;
namespace SQSCreateQueue
{
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class to create a queue
class Program
{
private const string MaxReceiveCount = "10";
private const string ReceiveMessageWaitTime = "2";
private const int MaxArgs = 3;
static async Task Main(string[] args)
{
// Parse the command line and show help if necessary
var parsedArgs = CommandLine.Parse(args);
if(parsedArgs.Count > MaxArgs)
CommandLine.ErrorExit(
"\nToo many command-line arguments.\nRun the command with no arguments to see help.");
// Create the Amazon SQS client
var sqsClient = new AmazonSQSClient();
// In the case of no command-line arguments, just show help and the existing queues
if(parsedArgs.Count == 0)
{
PrintHelp();
Console.WriteLine("\nNo arguments specified.");
Console.Write("Do you want to see a list of the existing queues? ((y) or n): ");
string response = Console.ReadLine();
if((string.IsNullOrEmpty(response)) || (response.ToLower() == "y"))
await ShowQueues(sqsClient);
return;
}
// Get the application arguments from the parsed list
string queueName =
CommandLine.GetArgument(parsedArgs, null, "-q", "--queue-name");
string deadLetterQueueUrl =
CommandLine.GetArgument(parsedArgs, null, "-d", "--dead-letter-queue");
string maxReceiveCount =
CommandLine.GetArgument(parsedArgs, MaxReceiveCount, "-m", "--max-receive-count");
string receiveWaitTime =
CommandLine.GetArgument(parsedArgs, ReceiveMessageWaitTime, "-w", "--wait-time");
if(string.IsNullOrEmpty(queueName))
CommandLine.ErrorExit(
"\nYou must supply a queue name.\nRun the command with no arguments to see help.");
// If a dead-letter queue wasn't given, create one
if(string.IsNullOrEmpty(deadLetterQueueUrl))
{
Console.WriteLine("\nNo dead-letter queue was specified. Creating one...");
deadLetterQueueUrl = await CreateQueue(sqsClient, queueName + "__dlq");
Console.WriteLine($"Your new dead-letter queue:");
await ShowAllAttributes(sqsClient, deadLetterQueueUrl);
}
// Create the message queue
string messageQueueUrl = await CreateQueue(
sqsClient, queueName, deadLetterQueueUrl, maxReceiveCount, receiveWaitTime);
Console.WriteLine($"Your new message queue:");
await ShowAllAttributes(sqsClient, messageQueueUrl);
}
//
// Method to show a list of the existing queues
private static async Task ShowQueues(IAmazonSQS sqsClient)
{
ListQueuesResponse responseList = await sqsClient.ListQueuesAsync("");
Console.WriteLine();
foreach(string qUrl in responseList.QueueUrls)
{
// Get and show all attributes. Could also get a subset.
await ShowAllAttributes(sqsClient, qUrl);
}
}
//
// Method to create a queue. Returns the queue URL.
private static async Task CreateQueue(
IAmazonSQS sqsClient, string qName, string deadLetterQueueUrl=null,
string maxReceiveCount=null, string receiveWaitTime=null)
{
var attrs = new Dictionary();
// If a dead-letter queue is given, create a message queue
if(!string.IsNullOrEmpty(deadLetterQueueUrl))
{
attrs.Add(QueueAttributeName.ReceiveMessageWaitTimeSeconds, receiveWaitTime);
attrs.Add(QueueAttributeName.RedrivePolicy,
$"{{\"deadLetterTargetArn\":\"{await GetQueueArn(sqsClient, deadLetterQueueUrl)}\"," +
$"\"maxReceiveCount\":\"{maxReceiveCount}\"}}");
// Add other attributes for the message queue such as VisibilityTimeout
}
// If no dead-letter queue is given, create one of those instead
//else
//{
// // Add attributes for the dead-letter queue as needed
// attrs.Add();
//}
// Create the queue
CreateQueueResponse responseCreate = await sqsClient.CreateQueueAsync(
new CreateQueueRequest{QueueName = qName, Attributes = attrs});
return responseCreate.QueueUrl;
}
//
// Method to get the ARN of a queue
private static async Task GetQueueArn(IAmazonSQS sqsClient, string qUrl)
{
GetQueueAttributesResponse responseGetAtt = await sqsClient.GetQueueAttributesAsync(
qUrl, new List{QueueAttributeName.QueueArn});
return responseGetAtt.QueueARN;
}
//
// Method to show all attributes of a queue
private static async Task ShowAllAttributes(IAmazonSQS sqsClient, string qUrl)
{
var attributes = new List{ QueueAttributeName.All };
GetQueueAttributesResponse responseGetAtt =
await sqsClient.GetQueueAttributesAsync(qUrl, attributes);
Console.WriteLine($"Queue: {qUrl}");
foreach(var att in responseGetAtt.Attributes)
Console.WriteLine($"\t{att.Key}: {att.Value}");
}
//
// Command-line help
private static void PrintHelp()
{
Console.WriteLine(
"\nUsage: SQSCreateQueue -q [-d ]" +
" [-m ] [-w ]" +
"\n -q, --queue-name: The name of the queue you want to create." +
"\n -d, --dead-letter-queue: The URL of an existing queue to be used as the dead-letter queue."+
"\n If this argument isn't supplied, a new dead-letter queue will be created." +
"\n -m, --max-receive-count: The value for maxReceiveCount in the RedrivePolicy of the queue." +
$"\n Default is {MaxReceiveCount}." +
"\n -w, --wait-time: The value for ReceiveMessageWaitTimeSeconds of the queue for long polling." +
$"\n Default is {ReceiveMessageWaitTime}.");
}
}
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class that represents a command line on the console or terminal.
// (This is the same for all examples. When you have seen it once, you can ignore it.)
static class CommandLine
{
//
// Method to parse a command line of the form: "--key value" or "-k value".
//
// Parameters:
// - args: The command-line arguments passed into the application by the system.
//
// Returns:
// A Dictionary with string Keys and Values.
//
// If a key is found without a matching value, Dictionary.Value is set to the key
// (including the dashes).
// If a value is found without a matching key, Dictionary.Key is set to "--NoKeyN",
// where "N" represents sequential numbers.
public static Dictionary Parse(string[] args)
{
var parsedArgs = new Dictionary();
int i = 0, n = 0;
while(i < args.Length)
{
// If the first argument in this iteration starts with a dash it's an option.
if(args[i].StartsWith("-"))
{
var key = args[i++];
var value = key;
// Check to see if there's a value that goes with this option?
if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++];
parsedArgs.Add(key, value);
}
// If the first argument in this iteration doesn't start with a dash, it's a value
else
{
parsedArgs.Add("--NoKey" + n.ToString(), args[i++]);
n++;
}
}
return parsedArgs;
}
//
// Method to get an argument from the parsed command-line arguments
//
// Parameters:
// - parsedArgs: The Dictionary object returned from the Parse() method (shown above).
// - defaultValue: The default string to return if the specified key isn't in parsedArgs.
// - keys: An array of keys to look for in parsedArgs.
public static string GetArgument(
Dictionary parsedArgs, string defaultReturn, params string[] keys)
{
string retval = null;
foreach(var key in keys)
if(parsedArgs.TryGetValue(key, out retval)) break;
return retval ?? defaultReturn;
}
//
// Method to exit the application with an error.
public static void ErrorExit(string msg, int code=1)
{
Console.WriteLine("\nError");
Console.WriteLine(msg);
Environment.Exit(code);
}
}
}
```
## Additional considerations
+ Your queue name must be composed of alphanumeric characters, hyphens, and underscores.
+ Queue names and queue URLs are case-sensitive
+ If you need the queue URL but only have the queue name, use one of the `AmazonSQSClient.GetQueueUrlAsync` methods.
+ For information about the various queue attributes you can set, see [CreateQueueRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TCreateQueueRequest.html) in the [AWS SDK for .NET API Reference](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/) or [SetQueueAttributes](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SetQueueAttributes.html) in the [Amazon Simple Queue Service API Reference](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/).
+ This example specifies long polling for all messages on the queue that you create. This is done by using the `ReceiveMessageWaitTimeSeconds` attribute.
You can also specify long polling during a call to the `ReceiveMessageAsync` methods of the [AmazonSQSClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TSQSClient.html) class. For more information, see [Receiving Amazon SQS messages](ReceiveMessage.md).
For information about short polling versus long polling, see [Short and long polling](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-short-and-long-polling.html) in the *Amazon Simple Queue Service Developer Guide*.
+ A dead letter queue is one that other (source) queues can target for messages that aren't processed successfully. For more information, see [Amazon SQS dead-letter queues](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html) in the Amazon Simple Queue Service Developer Guide.
+ You can also see the list of queues and the results of this example in the [Amazon SQS console](https://console.aws.amazon.com/sqs).
# Updating Amazon SQS queues
This example shows you how to use the AWS SDK for .NET to update an Amazon SQS queue. After some checks, the application updates the given attribute with the given value, and then shows all attributes for the queue.
If only the queue URL is included in the command-line arguments, the application simply shows all attributes for the queue.
The following sections provide snippets of this example. The [complete code for the example](#UpdateSqsQueue-complete-code) is shown after that, and can be built and run as is.
**Topics**
+ [Show queue attributes](#UpdateSqsQueue-show-attributes)
+ [Validate attribute name](#UpdateSqsQueue-validate-attribute)
+ [Update queue attribute](#UpdateSqsQueue-update-attribute)
+ [Complete code](#UpdateSqsQueue-complete-code)
+ [Additional considerations](#UpdateSqsQueue-additional)
## Show queue attributes
The following snippet shows the attributes of the queue identified by the given queue URL.
The example [at the end of this topic](#UpdateSqsQueue-complete-code) shows this snippet in use.
```
//
// Method to show all attributes of a queue
private static async Task ShowAllAttributes(IAmazonSQS sqsClient, string qUrl)
{
GetQueueAttributesResponse responseGetAtt =
await sqsClient.GetQueueAttributesAsync(qUrl,
new List{ QueueAttributeName.All });
Console.WriteLine($"Queue: {qUrl}");
foreach(var att in responseGetAtt.Attributes)
Console.WriteLine($"\t{att.Key}: {att.Value}");
}
```
## Validate attribute name
The following snippet validates the name of the attribute being updated.
The example [at the end of this topic](#UpdateSqsQueue-complete-code) shows this snippet in use.
```
//
// Method to check the name of the attribute
private static bool ValidAttribute(string attribute)
{
var attOk = false;
var qAttNameType = typeof(QueueAttributeName);
List qAttNamefields = new List();
foreach(var field in qAttNameType.GetFields())
qAttNamefields.Add(field.Name);
foreach(var name in qAttNamefields)
if(attribute == name) { attOk = true; break; }
return attOk;
}
```
## Update queue attribute
The following snippet updates an attribute of the queue identified by the given queue URL.
The example [at the end of this topic](#UpdateSqsQueue-complete-code) shows this snippet in use.
```
//
// Method to update a queue attribute
private static async Task UpdateAttribute(
IAmazonSQS sqsClient, string qUrl, string attribute, string value)
{
await sqsClient.SetQueueAttributesAsync(qUrl,
new Dictionary{{attribute, value}});
}
```
## Complete code
This section shows relevant references and the complete code for this example.
### SDK references
NuGet packages:
+ [AWSSDK.SQS](https://www.nuget.org/packages/AWSSDK.SQS)
Programming elements:
+ Namespace [Amazon.SQS](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/NSQS.html)
Class [AmazonSQSClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TSQSClient.html)
Class [QueueAttributeName](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TQueueAttributeName.html)
+ Namespace [Amazon.SQS.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/NSQSModel.html)
Class [GetQueueAttributesResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TGetQueueAttributesResponse.html)
### The code
```
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Amazon.SQS;
using Amazon.SQS.Model;
namespace SQSUpdateQueue
{
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class to update a queue
class Program
{
private const int MaxArgs = 3;
private const int InvalidArgCount = 2;
static async Task Main(string[] args)
{
// Parse the command line and show help if necessary
var parsedArgs = CommandLine.Parse(args);
if(parsedArgs.Count == 0)
{
PrintHelp();
return;
}
if((parsedArgs.Count > MaxArgs) || (parsedArgs.Count == InvalidArgCount))
CommandLine.ErrorExit("\nThe number of command-line arguments is incorrect." +
"\nRun the command with no arguments to see help.");
// Get the application arguments from the parsed list
var qUrl = CommandLine.GetArgument(parsedArgs, null, "-q");
var attribute = CommandLine.GetArgument(parsedArgs, null, "-a");
var value = CommandLine.GetArgument(parsedArgs, null, "-v", "--value");
if(string.IsNullOrEmpty(qUrl))
CommandLine.ErrorExit("\nYou must supply at least a queue URL." +
"\nRun the command with no arguments to see help.");
// Create the Amazon SQS client
var sqsClient = new AmazonSQSClient();
// In the case of one command-line argument, just show the attributes for the queue
if(parsedArgs.Count == 1)
await ShowAllAttributes(sqsClient, qUrl);
// Otherwise, attempt to update the given queue attribute with the given value
else
{
// Check to see if the attribute is valid
if(ValidAttribute(attribute))
{
// Perform the update and then show all the attributes of the queue
await UpdateAttribute(sqsClient, qUrl, attribute, value);
await ShowAllAttributes(sqsClient, qUrl);
}
else
{
Console.WriteLine($"\nThe given attribute name, {attribute}, isn't valid.");
}
}
}
//
// Method to show all attributes of a queue
private static async Task ShowAllAttributes(IAmazonSQS sqsClient, string qUrl)
{
GetQueueAttributesResponse responseGetAtt =
await sqsClient.GetQueueAttributesAsync(qUrl,
new List{ QueueAttributeName.All });
Console.WriteLine($"Queue: {qUrl}");
foreach(var att in responseGetAtt.Attributes)
Console.WriteLine($"\t{att.Key}: {att.Value}");
}
//
// Method to check the name of the attribute
private static bool ValidAttribute(string attribute)
{
var attOk = false;
var qAttNameType = typeof(QueueAttributeName);
List qAttNamefields = new List();
foreach(var field in qAttNameType.GetFields())
qAttNamefields.Add(field.Name);
foreach(var name in qAttNamefields)
if(attribute == name) { attOk = true; break; }
return attOk;
}
//
// Method to update a queue attribute
private static async Task UpdateAttribute(
IAmazonSQS sqsClient, string qUrl, string attribute, string value)
{
await sqsClient.SetQueueAttributesAsync(qUrl,
new Dictionary{{attribute, value}});
}
//
// Command-line help
private static void PrintHelp()
{
Console.WriteLine("\nUsage: SQSUpdateQueue -q queue_url [-a attribute -v value]");
Console.WriteLine(" -q: The URL of the queue you want to update.");
Console.WriteLine(" -a: The name of the attribute to update.");
Console.WriteLine(" -v, --value: The value to assign to the attribute.");
}
}
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class that represents a command line on the console or terminal.
// (This is the same for all examples. When you have seen it once, you can ignore it.)
static class CommandLine
{
//
// Method to parse a command line of the form: "--key value" or "-k value".
//
// Parameters:
// - args: The command-line arguments passed into the application by the system.
//
// Returns:
// A Dictionary with string Keys and Values.
//
// If a key is found without a matching value, Dictionary.Value is set to the key
// (including the dashes).
// If a value is found without a matching key, Dictionary.Key is set to "--NoKeyN",
// where "N" represents sequential numbers.
public static Dictionary Parse(string[] args)
{
var parsedArgs = new Dictionary();
int i = 0, n = 0;
while(i < args.Length)
{
// If the first argument in this iteration starts with a dash it's an option.
if(args[i].StartsWith("-"))
{
var key = args[i++];
var value = key;
// Check to see if there's a value that goes with this option?
if((i < args.Length) && (!args[i].StartsWith("-"))) value = args[i++];
parsedArgs.Add(key, value);
}
// If the first argument in this iteration doesn't start with a dash, it's a value
else
{
parsedArgs.Add("--NoKey" + n.ToString(), args[i++]);
n++;
}
}
return parsedArgs;
}
//
// Method to get an argument from the parsed command-line arguments
//
// Parameters:
// - parsedArgs: The Dictionary object returned from the Parse() method (shown above).
// - defaultValue: The default string to return if the specified key isn't in parsedArgs.
// - keys: An array of keys to look for in parsedArgs.
public static string GetArgument(
Dictionary parsedArgs, string defaultReturn, params string[] keys)
{
string retval = null;
foreach(var key in keys)
if(parsedArgs.TryGetValue(key, out retval)) break;
return retval ?? defaultReturn;
}
//
// Method to exit the application with an error.
public static void ErrorExit(string msg, int code=1)
{
Console.WriteLine("\nError");
Console.WriteLine(msg);
Environment.Exit(code);
}
}
}
```
## Additional considerations
+ To update the `RedrivePolicy` attribute, you must quote the entire value and escape the quotes for the key/value pairs, as appropriate for you operating system.
On Windows, for example, the value is constructed in a manner similar to the following:
```
"{\"deadLetterTargetArn\":\"DEAD_LETTER-QUEUE-ARN\",\"maxReceiveCount\":\"10\"}"
```
# Deleting Amazon SQS queues
This example shows you how to use the AWS SDK for .NET to delete an Amazon SQS queue. The application deletes the queue, waits for up to a given amount of time for the queue to be gone, and then shows a list of the remaining queues.
If you don't supply any command-line arguments, the application simply shows a list of the existing queues.
The following sections provide snippets of this example. The [complete code for the example](#DeleteSqsQueue-complete-code) is shown after that, and can be built and run as is.
**Topics**
+ [Delete the queue](#DeleteSqsQueue-delete-queue)
+ [Wait for the queue to be gone](#DeleteSqsQueue-wait)
+ [Show a list of existing queues](#DeleteSqsQueue-list-queues)
+ [Complete code](#DeleteSqsQueue-complete-code)
+ [Additional considerations](#DeleteSqsQueue-additional)
## Delete the queue
The following snippet deletes the queue identified by the given queue URL.
The example [at the end of this topic](#DeleteSqsQueue-complete-code) shows this snippet in use.
```
//
// Method to delete an SQS queue
private static async Task DeleteQueue(IAmazonSQS sqsClient, string qUrl)
{
Console.WriteLine($"Deleting queue {qUrl}...");
await sqsClient.DeleteQueueAsync(qUrl);
Console.WriteLine($"Queue {qUrl} has been deleted.");
}
```
## Wait for the queue to be gone
The following snippet waits for the deletion process to finish, which might take 60 seconds.
The example [at the end of this topic](#DeleteSqsQueue-complete-code) shows this snippet in use.
```
//
// Method to wait up to a given number of seconds
private static async Task Wait(
IAmazonSQS sqsClient, int numSeconds, string qUrl)
{
Console.WriteLine($"Waiting for up to {numSeconds} seconds.");
Console.WriteLine("Press any key to stop waiting. (Response might be slightly delayed.)");
for(int i=0; i
The following snippet shows a list of the existing queues in the SQS client's region.
The example [at the end of this topic](#DeleteSqsQueue-complete-code) shows this snippet in use.
```
//
// Method to show a list of the existing queues
private static async Task ListQueues(IAmazonSQS sqsClient)
{
ListQueuesResponse responseList = await sqsClient.ListQueuesAsync("");
Console.WriteLine("\nList of queues:");
foreach(var qUrl in responseList.QueueUrls)
Console.WriteLine($"- {qUrl}");
}
```
## Complete code
This section shows relevant references and the complete code for this example.
### SDK references
NuGet packages:
+ [AWSSDK.SQS](https://www.nuget.org/packages/AWSSDK.SQS)
Programming elements:
+ Namespace [Amazon.SQS](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/NSQS.html)
Class [AmazonSQSClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TSQSClient.html)
+ Namespace [Amazon.SQS.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/NSQSModel.html)
Class [ListQueuesResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TListQueuesResponse.html)
### The code
```
using System;
using System.Threading;
using System.Threading.Tasks;
using Amazon.SQS;
using Amazon.SQS.Model;
namespace SQSDeleteQueue
{
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class to update a queue
class Program
{
private const int TimeToWait = 60;
static async Task Main(string[] args)
{
// Create the Amazon SQS client
var sqsClient = new AmazonSQSClient();
// If no command-line arguments, just show a list of the queues
if(args.Length == 0)
{
Console.WriteLine("\nUsage: SQSCreateQueue queue_url");
Console.WriteLine(" queue_url - The URL of the queue you want to delete.");
Console.WriteLine("\nNo arguments specified.");
Console.Write("Do you want to see a list of the existing queues? ((y) or n): ");
var response = Console.ReadLine();
if((string.IsNullOrEmpty(response)) || (response.ToLower() == "y"))
await ListQueues(sqsClient);
return;
}
// If given a queue URL, delete that queue
if(args[0].StartsWith("https://sqs."))
{
// Delete the queue
await DeleteQueue(sqsClient, args[0]);
// Wait for a little while because it takes a while for the queue to disappear
await Wait(sqsClient, TimeToWait, args[0]);
// Show a list of the remaining queues
await ListQueues(sqsClient);
}
else
{
Console.WriteLine("The command-line argument isn't a queue URL:");
Console.WriteLine($"{args[0]}");
}
}
//
// Method to delete an SQS queue
private static async Task DeleteQueue(IAmazonSQS sqsClient, string qUrl)
{
Console.WriteLine($"Deleting queue {qUrl}...");
await sqsClient.DeleteQueueAsync(qUrl);
Console.WriteLine($"Queue {qUrl} has been deleted.");
}
//
// Method to wait up to a given number of seconds
private static async Task Wait(
IAmazonSQS sqsClient, int numSeconds, string qUrl)
{
Console.WriteLine($"Waiting for up to {numSeconds} seconds.");
Console.WriteLine("Press any key to stop waiting. (Response might be slightly delayed.)");
for(int i=0; i
+ The `DeleteQueueAsync` API call doesn't check to see if the queue you're deleting is being used as a dead-letter queue. A more sophisticated procedure could check for this.
+ You can also see the list of queues and the results of this example in the [Amazon SQS console](https://console.aws.amazon.com/sqs).
# Sending Amazon SQS messages
This example shows you how to use the AWS SDK for .NET to send messages to an Amazon SQS queue, which you can create [programmatically](CreateQueue.md) or by using the [Amazon SQS console](https://console.aws.amazon.com/sqs). The application sends a single message to the queue and then a batch of messages. The application then waits for user input, which can be additional messages to send to the queue or a request to exit the application.
This example and the [next example about receiving messages](ReceiveMessage.md) can be used together to see message flow in Amazon SQS.
The following sections provide snippets of this example. The [complete code for the example](#SendMessage-complete-code) is shown after that, and can be built and run as is.
**Topics**
+ [Send a message](#SendMessage-send-message)
+ [Send a batch of messages](#SendMessage-send-batch)
+ [Delete all messages from the queue](#SendMessage-purge-messages)
+ [Complete code](#SendMessage-complete-code)
+ [Additional considerations](#SendMessage-additional)
## Send a message
The following snippet sends a message to the queue identified by the given queue URL.
The example [at the end of this topic](#SendMessage-complete-code) shows this snippet in use.
```
//
// Method to put a message on a queue
// Could be expanded to include message attributes, etc., in a SendMessageRequest
private static async Task SendMessage(
IAmazonSQS sqsClient, string qUrl, string messageBody)
{
SendMessageResponse responseSendMsg =
await sqsClient.SendMessageAsync(qUrl, messageBody);
Console.WriteLine($"Message added to queue\n {qUrl}");
Console.WriteLine($"HttpStatusCode: {responseSendMsg.HttpStatusCode}");
}
```
## Send a batch of messages
The following snippet sends a batch of messages to the queue identified by the given queue URL.
The example [at the end of this topic](#SendMessage-complete-code) shows this snippet in use.
```
//
// Method to put a batch of messages on a queue
// Could be expanded to include message attributes, etc.,
// in the SendMessageBatchRequestEntry objects
private static async Task SendMessageBatch(
IAmazonSQS sqsClient, string qUrl, List messages)
{
Console.WriteLine($"\nSending a batch of messages to queue\n {qUrl}");
SendMessageBatchResponse responseSendBatch =
await sqsClient.SendMessageBatchAsync(qUrl, messages);
// Could test responseSendBatch.Failed here
foreach(SendMessageBatchResultEntry entry in responseSendBatch.Successful)
Console.WriteLine($"Message {entry.Id} successfully queued.");
}
```
## Delete all messages from the queue
The following snippet deletes all messages from the queue identified by the given queue URL. This is also known as *purging the queue*.
The example [at the end of this topic](#SendMessage-complete-code) shows this snippet in use.
```
//
// Method to delete all messages from the queue
private static async Task DeleteAllMessages(IAmazonSQS sqsClient, string qUrl)
{
Console.WriteLine($"\nPurging messages from queue\n {qUrl}...");
PurgeQueueResponse responsePurge = await sqsClient.PurgeQueueAsync(qUrl);
Console.WriteLine($"HttpStatusCode: {responsePurge.HttpStatusCode}");
}
```
## Complete code
This section shows relevant references and the complete code for this example.
### SDK references
NuGet packages:
+ [AWSSDK.SQS](https://www.nuget.org/packages/AWSSDK.SQS)
Programming elements:
+ Namespace [Amazon.SQS](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/NSQS.html)
Class [AmazonSQSClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TSQSClient.html)
+ Namespace [Amazon.SQS.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/NSQSModel.html)
Class [PurgeQueueResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TPurgeQueueResponse.html)
Class [SendMessageBatchResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TSendMessageBatchResponse.html)
Class [SendMessageResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TSendMessageResponse.html)
Class [SendMessageBatchRequestEntry](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TSendMessageBatchRequestEntry.html)
Class [SendMessageBatchResultEntry](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TSendMessageBatchResultEntry.html)
### The code
```
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Amazon.SQS;
using Amazon.SQS.Model;
namespace SQSSendMessages
{
// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
// Class to send messages to a queue
class Program
{
// Some example messages to send to the queue
private const string JsonMessage = "{\"product\":[{\"name\":\"Product A\",\"price\": \"32\"},{\"name\": \"Product B\",\"price\": \"27\"}]}";
private const string XmlMessage = "";
private const string CustomMessage = "||product|Product A|32||product|Product B|27||";
private const string TextMessage = "Just a plain text message.";
static async Task Main(string[] args)
{
// Do some checks on the command-line
if(args.Length == 0)
{
Console.WriteLine("\nUsage: SQSSendMessages queue_url");
Console.WriteLine(" queue_url - The URL of an existing SQS queue.");
return;
}
if(!args[0].StartsWith("https://sqs."))
{
Console.WriteLine("\nThe command-line argument isn't a queue URL:");
Console.WriteLine($"{args[0]}");
return;
}
// Create the Amazon SQS client
var sqsClient = new AmazonSQSClient();
// (could verify that the queue exists)
// Send some example messages to the given queue
// A single message
await SendMessage(sqsClient, args[0], JsonMessage);
// A batch of messages
var batchMessages = new List{
new SendMessageBatchRequestEntry("xmlMsg", XmlMessage),
new SendMessageBatchRequestEntry("customeMsg", CustomMessage),
new SendMessageBatchRequestEntry("textMsg", TextMessage)};
await SendMessageBatch(sqsClient, args[0], batchMessages);
// Let the user send their own messages or quit
await InteractWithUser(sqsClient, args[0]);
// Delete all messages that are still in the queue
await DeleteAllMessages(sqsClient, args[0]);
}
//
// Method to put a message on a queue
// Could be expanded to include message attributes, etc., in a SendMessageRequest
private static async Task SendMessage(
IAmazonSQS sqsClient, string qUrl, string messageBody)
{
SendMessageResponse responseSendMsg =
await sqsClient.SendMessageAsync(qUrl, messageBody);
Console.WriteLine($"Message added to queue\n {qUrl}");
Console.WriteLine($"HttpStatusCode: {responseSendMsg.HttpStatusCode}");
}
//
// Method to put a batch of messages on a queue
// Could be expanded to include message attributes, etc.,
// in the SendMessageBatchRequestEntry objects
private static async Task SendMessageBatch(
IAmazonSQS sqsClient, string qUrl, List messages)
{
Console.WriteLine($"\nSending a batch of messages to queue\n {qUrl}");
SendMessageBatchResponse responseSendBatch =
await sqsClient.SendMessageBatchAsync(qUrl, messages);
// Could test responseSendBatch.Failed here
foreach(SendMessageBatchResultEntry entry in responseSendBatch.Successful)
Console.WriteLine($"Message {entry.Id} successfully queued.");
}
//
// Method to get input from the user
// They can provide messages to put in the queue or exit the application
private static async Task InteractWithUser(IAmazonSQS sqsClient, string qUrl)
{
string response;
while (true)
{
// Get the user's input
Console.WriteLine("\nType a message for the queue or \"exit\" to quit:");
response = Console.ReadLine();
if(response.ToLower() == "exit") break;
// Put the user's message in the queue
await SendMessage(sqsClient, qUrl, response);
}
}
//
// Method to delete all messages from the queue
private static async Task DeleteAllMessages(IAmazonSQS sqsClient, string qUrl)
{
Console.WriteLine($"\nPurging messages from queue\n {qUrl}...");
PurgeQueueResponse responsePurge = await sqsClient.PurgeQueueAsync(qUrl);
Console.WriteLine($"HttpStatusCode: {responsePurge.HttpStatusCode}");
}
}
}
```
## Additional considerations
+ For information about various limitations on messages, including the allowed characters, see [Quotas related to messages](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-quotas.html#quotas-messages) in the [Amazon Simple Queue Service Developer Guide](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/).
+ Messages stay in queues until they are deleted or the queue is purged. When a message has been received by an application, it won't be visible in the queue even though it still exists in the queue. For more information about visibility timeouts, see [Amazon SQS visibility timeout](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/AboutVT.html).
+ In additional to the message body, you can also add attributes to messages. For more information, see [Message metadata](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-message-metadata.html).
# Receiving Amazon SQS messages
This example shows you how to use the AWS SDK for .NET to receive messages from an Amazon SQS queue, which you can create [programmatically](CreateQueue.md) or by using the [Amazon SQS console](https://console.aws.amazon.com/sqs). The application reads a single message from the queue, processes the message (in this case, displays the message body on the console), and then deletes the message from the queue. The application repeats these steps until the user types a key on the keyboard.
This example and the [previous example about sending messages](SendMessage.md) can be used together to see message flow in Amazon SQS.
The following sections provide snippets of this example. The [complete code for the example](#ReceiveMessage-complete-code) is shown after that, and can be built and run as is.
**Topics**
+ [Receive a message](#ReceiveMessage-receive)
+ [Delete a message](#ReceiveMessage-delete)
+ [Complete code](#ReceiveMessage-complete-code)
+ [Additional considerations](#ReceiveMessage-additional)
## Receive a message
The following snippet receives a message from the queue identified by the given queue URL.
The example [at the end of this topic](#ReceiveMessage-complete-code) shows this snippet in use.
```
//
// Method to read a message from the given queue
// In this example, it gets one message at a time
private static async Task GetMessage(
IAmazonSQS sqsClient, string qUrl, int waitTime=0)
{
return await sqsClient.ReceiveMessageAsync(new ReceiveMessageRequest{
QueueUrl=qUrl,
MaxNumberOfMessages=MaxMessages,
WaitTimeSeconds=waitTime
// (Could also request attributes, set visibility timeout, etc.)
});
}
```
## Delete a message
The following snippet deletes a message from the queue identified by the given queue URL.
The example [at the end of this topic](#ReceiveMessage-complete-code) shows this snippet in use.
```
//
// Method to delete a message from a queue
private static async Task DeleteMessage(
IAmazonSQS sqsClient, Message message, string qUrl)
{
Console.WriteLine($"\nDeleting message {message.MessageId} from queue...");
await sqsClient.DeleteMessageAsync(qUrl, message.ReceiptHandle);
}
```
## Complete code
This section shows relevant references and the complete code for this example.
### SDK references
NuGet packages:
+ [AWSSDK.SQS](https://www.nuget.org/packages/AWSSDK.SQS)
Programming elements:
+ Namespace [Amazon.SQS](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/NSQS.html)
Class [AmazonSQSClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TSQSClient.html)
+ Namespace [Amazon.SQS.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/NSQSModel.html)
Class [ReceiveMessageRequest](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TReceiveMessageRequest.html)
Class [ReceiveMessageResponse](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TReceiveMessageResponse.html)
### The code
```
using System;
using System.Threading.Tasks;
using Amazon.SQS;
using Amazon.SQS.Model;
namespace SQSReceiveMessages
{
class Program
{
private const int MaxMessages = 1;
private const int WaitTime = 2;
static async Task Main(string[] args)
{
// Do some checks on the command-line
if(args.Length == 0)
{
Console.WriteLine("\nUsage: SQSReceiveMessages queue_url");
Console.WriteLine(" queue_url - The URL of an existing SQS queue.");
return;
}
if(!args[0].StartsWith("https://sqs."))
{
Console.WriteLine("\nThe command-line argument isn't a queue URL:");
Console.WriteLine($"{args[0]}");
return;
}
// Create the Amazon SQS client
var sqsClient = new AmazonSQSClient();
// (could verify that the queue exists)
// Read messages from the queue and perform appropriate actions
Console.WriteLine($"Reading messages from queue\n {args[0]}");
Console.WriteLine("Press any key to stop. (Response might be slightly delayed.)");
do
{
var msg = await GetMessage(sqsClient, args[0], WaitTime);
if(msg.Messages.Count != 0)
{
if(ProcessMessage(msg.Messages[0]))
await DeleteMessage(sqsClient, msg.Messages[0], args[0]);
}
} while(!Console.KeyAvailable);
}
//
// Method to read a message from the given queue
// In this example, it gets one message at a time
private static async Task GetMessage(
IAmazonSQS sqsClient, string qUrl, int waitTime=0)
{
return await sqsClient.ReceiveMessageAsync(new ReceiveMessageRequest{
QueueUrl=qUrl,
MaxNumberOfMessages=MaxMessages,
WaitTimeSeconds=waitTime
// (Could also request attributes, set visibility timeout, etc.)
});
}
//
// Method to process a message
// In this example, it simply prints the message
private static bool ProcessMessage(Message message)
{
Console.WriteLine($"\nMessage body of {message.MessageId}:");
Console.WriteLine($"{message.Body}");
return true;
}
//
// Method to delete a message from a queue
private static async Task DeleteMessage(
IAmazonSQS sqsClient, Message message, string qUrl)
{
Console.WriteLine($"\nDeleting message {message.MessageId} from queue...");
await sqsClient.DeleteMessageAsync(qUrl, message.ReceiptHandle);
}
}
}
```
## Additional considerations
+ To specify long polling, this example uses the `WaitTimeSeconds` property for each call to the `ReceiveMessageAsync` method.
You can also specify long polling for all messages on a queue by using the `ReceiveMessageWaitTimeSeconds` attribute when [creating](CreateQueue.md) or [updating](UpdateSqsQueue.md) the queue.
For information about short polling versus long polling, see [Short and long polling](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-short-and-long-polling.html) in the *Amazon Simple Queue Service Developer Guide*.
+ During message processing, you can use the receipt handle to change the message visibility timeout. For information about how to do this, see the `ChangeMessageVisibilityAsync` methods of the [AmazonSQSClient](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TSQSClient.html) class.
+ Calling the `DeleteMessageAsync` method unconditionally removes the message from the queue, regardless of the visibility timeout setting.