Menu
AWS SDK for .NET
Developer Guide

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

Tutorial: Creating Amazon EC2 Instances with the AWS SDK for .NET

You can access the features of Amazon EC2 using the AWS SDK for .NET. For example, you can create, start, and terminate EC2 instances.

The sample code in this tutorial is written in C#, but you can use the AWS SDK for .NET with any compatible language. The AWS SDK for .NET installs a set of C# project templates, so the simplest way to start this project is to open Visual Studio, select New Project from the File menu, and then select AWS Empty Project.

Prerequisites

Before you begin, be sure that you have created an AWS account and that you have set up your AWS credentials. For more information, see Getting Started with the AWS SDK for .NET.

Tasks

The following tasks demonstrate how to manage EC2 instances using the AWS SDK for .NET.

Create an Amazon EC2 Client Using the the SDK

Create an Amazon EC2 client to manage your EC2 resources, such as instances and security groups. This client is represented by an AmazonEC2Client object, which you can create as follows:

Copy
var ec2Client = new AmazonEC2Client();

The permissions for the client object are determined by the policy that is attached to the profile that you specified in the App.config file. By default, we use the region specified in App.config. To use a different region, pass the appropriate RegionEndpoint value to the constructor. For more information, see Regions and Endpoints in the Amazon Web Services General Reference.

Create a Security Group Using the the SDK

Create a security group, which acts as a virtual firewall that controls the network traffic for one or more EC2 instances. By default, Amazon 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. You can create a security group using the Amazon EC2 console or the the SDK.

You create a security group for use in either EC2-Classic or EC2-VPC. For more information about EC2-Classic and EC2-VPC, see Supported Platforms in the Amazon EC2 User Guide for Windows Instances.

Alternatively, you can create a security group using the Amazon EC2 console. For more information, see Amazon EC2 Security Groups in the Amazon EC2 User Guide for Windows Instances.

Enumerating Your Security Groups

You can enumerate your security groups and check whether a particular security group exists.

To enumerate your security groups for EC2-Classic

Get the complete list of your security groups using DescribeSecurityGroups with no parameters. The following example checks each security group to see whether its name is my-sample-sg.

Copy
string secGroupName = "my-sample-sg"; SecurityGroup mySG = null; var dsgRequest = new DescribeSecurityGroupsRequest(); var dsgResponse = ec2Client.DescribeSecurityGroups(dsgRequest); List<SecurityGroup> mySGs = dsgResponse.SecurityGroups; foreach (SecurityGroup item in mySGs) { Console.WriteLine("Existing security group: " + item.GroupId); if (item.GroupName == secGroupName) { mySG = item; } }

To enumerate your security groups for a VPC

To enumerate the security groups for a particular VPC, use DescribeSecurityGroups with a filter. The following example checks each security group for a security group with the name my-sample-sg-vpc.

Copy
string secGroupName = "my-sample-sg-vpc"; SecurityGroup mySG = null; string vpcID = "vpc-f1663d98"; Filter vpcFilter = new Filter { Name = "vpc-id", Values = new List<string>() {vpcID} }; var dsgRequest = new DescribeSecurityGroupsRequest(); dsgRequest.Filters.Add(vpcFilter); var dsgResponse = ec2Client.DescribeSecurityGroups(dsgRequest); List<SecurityGroup> mySGs = dsgResponse.SecurityGroups; foreach (SecurityGroup item in mySGs) { Console.WriteLine("Existing security group: " + item.GroupId); if (item.GroupName == secGroupName) { mySG = item; } }

Creating a Security Group

The examples in this section follow from the examples in the previous section. If the security group doesn't already exist, create it. Note that if you were to specify the same name as an existing security group, CreateSecurityGroup throws an exception.

To create a security group for EC2-Classic

Create and initialize a CreateSecurityGroupRequest object. Assign a name and description to the GroupName and Description properties, respectively.

The CreateSecurityGroup method returns a CreateSecurityGroupResponse object. You can get the ID of the new security group from the response and then use DescribeSecurityGroups with the security group ID to get the SecurityGroup object for the security group.

Copy
if (mySG == null) { var newSGRequest = new CreateSecurityGroupRequest() { GroupName = secGroupName, Description = "My sample security group for EC2-Classic" }; var csgResponse = ec2Client.CreateSecurityGroup(newSGRequest); Console.WriteLine(); Console.WriteLine("New security group: " + csgResponse.GroupId); List<string> Groups = new List<string>() { csgResponse.GroupId }; var newSgRequest = new DescribeSecurityGroupsRequest() { GroupIds = Groups }; var newSgResponse = ec2Client.DescribeSecurityGroups(newSgRequest); mySG = newSgResponse.SecurityGroups[0]; }

To create a security group for EC2-VPC

Create and initialize a CreateSecurityGroupRequest object. Assign values to the GroupName, Description, and VpcId properties.

The CreateSecurityGroup method returns a CreateSecurityGroupResponse object. You can get the ID of the new security group from the response and then use DescribeSecurityGroups with the security group ID to get the SecurityGroup object for the security group.

Copy
if (mySG == null) { var newSGRequest = new CreateSecurityGroupRequest() { GroupName = secGroupName, Description = "My sample security group for EC2-VPC", VpcId = vpcID }; var csgResponse = ec2Client.CreateSecurityGroup(newSGRequest); Console.WriteLine(); Console.WriteLine("New security group: " + csgResponse.GroupId); List<string> Groups = new List<string>() { csgResponse.GroupId }; var newSgRequest = new DescribeSecurityGroupsRequest() { GroupIds = Groups }; var newSgResponse = ec2Client.DescribeSecurityGroups(newSgRequest); mySG = newSgResponse.SecurityGroups[0]; }

Adding Rules to Your Security Group

Use the following procedure to add a rule to allow inbound traffic on TCP port 3389 (RDP). This enables you to connect to a Windows instance. If you're launching a Linux instance, use TCP port 22 (SSH) instead.

Note

You can get the public IP address of your local computer using a service. For example, we provide the following service: http://checkip.amazonaws.com/. To locate another service that provides your IP address, use the search phrase "what is my IP address". If you are connecting through an ISP or from behind your firewall without a static IP address, you need to find out the range of IP addresses used by client computers.

The examples in this section follow from the examples in the previous sections. They assume that mySG is an existing security group.

To add a rule to a security group

  1. Create and initialize an IpPermission object.

    Copy
    string ipRange = "0.0.0.0/0"; List<string> ranges = new List<string>() {ipRange}; var ipPermission = new IpPermission() { IpProtocol = "tcp", FromPort = 3389, ToPort = 3389, IpRanges = ranges };
    IpProtocol

    The IP protocol.

    FromPort and ToPort

    The beginning and end of the port range. This example specifies a single port, 3389, which is used to communicate with Windows over RDP.

    IpRanges

    The IP addresses or address ranges, in CIDR notation. For convenience, this example uses 0.0.0.0/0, which authorizes network traffic from all IP addresses. This is acceptable for a short time in a test environment, but it's unsafe in a production environment.

  2. Create and initialize an AuthorizeSecurityGroupIngressRequest object.

    Copy
    var ingressRequest = new AuthorizeSecurityGroupIngressRequest(); ingressRequest.GroupId = mySG.GroupId; ingressRequest.IpPermissions.Add(ipPermission);
    GroupId

    The ID of the security group.

    IpPermissions

    The IpPermission object from step 1.

  3. (Optional) You can add additional rules to the IpPermissions collection before going to the next step.

  4. Pass the request object to the AuthorizeSecurityGroupIngress method, which returns an AuthorizeSecurityGroupIngressResponse object.

    Copy
    var ingressResponse = ec2Client.AuthorizeSecurityGroupIngress(ingressRequest); Console.WriteLine("New RDP rule for: " + ipRange);

Create a Key Pair Using the the SDK

You must specify a key pair when you launch an EC2 instance and specify the private key of the key pair when you connect to the instance. You can create a key pair or use an existing key pair that you've used when launching other instances. For more information, see Amazon EC2 Key Pairs in the Amazon EC2 User Guide for Windows Instances.

Enumerating Your Key Pairs

You can enumerate your key pairs and check whether a particular key pair exists.

To enumerate your key pairs

Get the complete list of your key pairs using DescribeKeyPairs with no parameters. The following example checks each key pair to see whether its name is my-sample-key.

Copy
string keyPairName = "my-sample-key"; KeyPairInfo myKeyPair = null; var dkpRequest = new DescribeKeyPairsRequest(); var dkpResponse = ec2Client.DescribeKeyPairs(dkpRequest); List<KeyPairInfo> myKeyPairs = dkpResponse.KeyPairs; foreach (KeyPairInfo item in myKeyPairs) { Console.WriteLine("Existing key pair: " + item.KeyName); if (item.KeyName == keyPairName) { myKeyPair = item; } }

Creating a Key Pair and Saving the Private Key

The example in this section follows from the example in the previous section. If the key pair doesn't already exist, create it. Be sure to save the private key now, because you can't retrieve it later.

To create a key pair and save the private key

Create and initialize a CreateKeyPairRequest object. Set the KeyName property to the name of the key pair.

Pass the request object to the CreateKeyPair method, which returns a CreateKeyPairResponse object.

The response object includes a CreateKeyPairResult property that contains the new key's KeyPair object. The KeyPair object's KeyMaterial property contains the unencrypted private key for the key pair. Save the private key as a .pem file in a safe location. You'll need this file when you connect to your instance. This example saves the private key in the current directory, using the name of the key pair as the base file name of the .pem file.

Copy
if (myKeyPair == null) { var newKeyRequest = new CreateKeyPairRequest() { KeyName = keyPairName }; var ckpResponse = ec2Client.CreateKeyPair(newKeyRequest); Console.WriteLine(); Console.WriteLine("New key: " + keyPairName); // Save the private key in a .pem file using (FileStream s = new FileStream(keyPairName + ".pem", FileMode.Create)) using (StreamWriter writer = new StreamWriter(s)) { writer.WriteLine(ckpResponse.KeyPair.KeyMaterial); } }

Topics