AWS Elastic Beanstalk
Developer Guide (API Version 2010-12-01)
AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Deploying an ASP.NET Core Application with AWS Elastic Beanstalk

In this tutorial, you walk through the process of building a new ASP.NET Core application and deploying it to Elastic Beanstalk. You will use the .NET Core SDK's dotnet command line tool to generate a basic command-line .NET Core application, install dependencies, compile code, and run applications locally.

Next, you modify the default Program class, and add an ASP.NET Startup class and configuration files to make an application that serves HTTP requests with ASP.NET and IIS. The dotnet publish command generates compiled classes and dependencies that you can bundle with a web.config file to create a site archive that you can deploy to an Elastic Beanstalk environment.

Elastic Beanstalk uses a deployment manifest to configure deployments for .NET Core applications, custom applications, and multiple .NET Core or MSBuild applications on a single server. To deploy a .NET Core application to a Windows Server environment, you add the site archive to an application source bundle with a deployment manifest. The deployment manifest tells Elastic Beanstalk the path at which the site should run and can be used to configure application pools and run multiple applications at different paths.

Note

The application source code is available here: dotnet-core-tutorial-source-v1.zip

The deployable source bundle is available here: dotnet-core-tutorial-bundle-v1.zip

Prerequisites

This tutorial uses the .NET Core SDK version 1.0.0-preview2 to generate a basic .NET Core application, run it locally, and build a deployable package.

To install the .NET Core SDK

  1. Download the installer from microsoft.com/net/core. Look for the link labeled .NET Core SDK for Windows.

  2. Run the installer and follow the instructions.

This tutorial uses a command line ZIP utility to create a source bundle that you can deploy to Elastic Beanstalk. To use the zip command in Windows, you can install UnxUtils, a lightweight collection of useful command-line utilities like zip and ls. (Alternatively, you can use Windows Explorer or any other ZIP utility to create source bundle archives.)

To install UnxUtils

  1. Download UnxUtils.

  2. Extract the archive to a local directory. For example, C:\Program Files (x86).

  3. Add the path to the binaries to your Windows PATH user variable. For example, C:\Program Files (x86)\UnxUtils\usr\local\wbin.

  4. Open a new command prompt window and run the zip command to verify that it works:

    Copy
    > zip Copyright (C) 1990-1999 Info-ZIP Type 'zip "-L"' for software license. ...

Generate a .NET Core Project

Use the dotnet command line tool to generate a new C# .NET Core project and run it locally. The default .NET Core application is a command line utility that prints Hello World! and then exits.

To generate a new .NET Core project

  1. Open a new command prompt and navigate to your user folder.

    Copy
    > cd %USERPROFILE%
  2. Create a directory for the project.

    Copy
    ~> mkdir dotnet-core-tutorial ~> cd dotnet-core-tutorial
  3. Use the dotnet new command to generate a new .NET Core project.

    Copy
    ~\dotnet-core-tutorial> dotnet new Created new C# project in C:\Users\me\dotnet-core-tutorial.
  4. Use the dotnet restore command to install dependencies.

    Copy
    ~\dotnet-core-tutorial> dotnet restore log : Restoring packages for C:\Users\me\dotnet-core-tutorial\project.json... log : Writing lock file to disk. Path: C:\Users\me\dotnet-core-tutorial\project.lock.json log : C:\Users\me\dotnet-core-tutorial\project.json log : Restore completed in 18101ms.
  5. Use the dotnet run command to build and run the application locally.

    Copy
    ~\dotnet-core-tutorial> dotnet run Project dotnet-core-tutorial (.NETCoreApp,Version=v1.0) will be compiled because expected outputs are missing Compiling dotnet-core-tutorial for .NETCoreApp,Version=v1.0 Compilation succeeded. 0 Warning(s) 0 Error(s) Time elapsed 00:00:08.3036217 Hello World!

The default application prints Hello World! to the console and exits. Before you deploy the application to Elastic Beanstalk, you will update it to serve HTTP requests with ASP.NET and IIS.

Launch an Elastic Beanstalk Environment

Use the AWS Management Console to launch an Elastic Beanstalk environment. Choose the Windows Server 2012R2 v1.2.0 platform configuration and accept the default settings and sample code. After you launch and configure your environment, you can deploy new source code at any time.

To launch an environment (console)

  1. Open the Elastic Beanstalk console with this preconfigured link: console.aws.amazon.com/elasticbeanstalk/home#/newApplication?applicationName=tutorials&environmentType=LoadBalanced

  2. For Platform, choose the platform that matches the language used by your application.

  3. For App code, choose Sample application.

  4. Choose Review and launch.

  5. Review all options and once you are satisfied with those options choose Create app.

Environment creation takes about 10 minutes. During this time you can update your source code.

Update the Source Code

Update the default application to use ASP.NET and IIS. ASP.NET is the website framework for .NET. IIS is the web server that runs the application on the EC2 instances in your Elastic Beanstalk environment.

Note

The source code is available here: dotnet-core-tutorial-source-v1.zip

To add ASP.NET and IIS support to your code

  1. Update Program.cs to run a web host builder.

    Example ~\dotnet-core-tutorial\Program.cs

    Copy
    using System; using Microsoft.AspNetCore.Hosting; using System.IO; namespace aspnetcoreapp { public class Program { public static void Main(string[] args) { var host = new WebHostBuilder() .UseKestrel() .UseContentRoot(Directory.GetCurrentDirectory()) .UseIISIntegration() .UseStartup<Startup>() .Build(); host.Run(); } } }
  2. Add a Startup.cs file to run an ASP.NET website.

    Example ~\dotnet-core-tutorial\Startup.cs

    Copy
    using System; using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Hosting; using Microsoft.AspNetCore.Http; namespace aspnetcoreapp { public class Startup { public void Configure(IApplicationBuilder app) { app.Run(context => { return context.Response.WriteAsync("Hello from ASP.NET Core!"); }); } } }
  3. Add a web.config file to configure the IIS server.

    Example ~\dotnet-core-tutorial\web.config

    Copy
    <?xml version="1.0" encoding="utf-8"?> <configuration> <system.webServer> <handlers> <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" /> </handlers> <aspNetCore processPath="dotnet" arguments=".\dotnet-core-tutorial.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" forwardWindowsAuthToken="false" /> </system.webServer> </configuration>
  4. Update project.json to include IIS middleware and include the web.config file in the output of dotnet publish.

    Example ~\dotnet-core-tutorial\project.json

    Copy
    { "version": "1.0.0-*", "buildOptions": { "debugType": "portable", "emitEntryPoint": true }, "dependencies": {}, "frameworks": { "netcoreapp1.0": { "dependencies": { "Microsoft.NETCore.App": { "type": "platform", "version": "1.0.0" }, "Microsoft.AspNetCore.Server.Kestrel": "1.0.0", "Microsoft.AspNetCore.Server.IISIntegration": "1.0.0" }, "imports": "dnxcore50" } }, "publishOptions": { "include": [ "web.config" ] } }

Next, you will install the new dependencies and run the ASP.NET website locally.

To run the website locally

  1. Use the dotnet restore command to install dependencies.

  2. Use the dotnet run command to build and run the app locally.

  3. Open localhost:5000 to view the site.

To run the application on a web server, you need to bundle the compiled source code with a web.config configuration file and runtime dependencies. The dotnet tool provides a publish command that gathers these files in a directory based on the configuration in project.json.

To build your website

  • Use the dotnet publish command to output compiled code and dependencies to a folder named site.

    Copy
    ~\dotnet-core-tutorial> dotnet publish -o site

To deploy the application to Elastic Beanstalk, bundle the site archive with a deployment manifest that tells Elastic Beanstalk how to run it.

To create a source bundle

  1. Add the files in the site folder to a ZIP archive.

    Copy
    ~\dotnet-core-tutorial> cd site ~\dotnet-core-tutorial\site> zip ../site.zip * adding: dotnet-core-tutorial.deps.json (164 bytes security) (deflated 81%) adding: dotnet-core-tutorial.dll (164 bytes security) (deflated 58%) adding: dotnet-core-tutorial.pdb (164 bytes security) (deflated 30%) adding: dotnet-core-tutorial.runtimeconfig.json (164 bytes security) (deflated 25%) adding: Microsoft.AspNetCore.Hosting.Abstractions.dll (164 bytes security) (deflated 48%) adding: Microsoft.AspNetCore.Hosting.dll (164 bytes security) (deflated 54%) adding: Microsoft.AspNetCore.Hosting.Server.Abstractions.dll (164 bytes security) (deflated 45%) adding: Microsoft.AspNetCore.Http.Abstractions.dll (164 bytes security) (deflated 52%) adding: Microsoft.AspNetCore.Http.dll (164 bytes security) (deflated 55%) adding: Microsoft.AspNetCore.Http.Extensions.dll (164 bytes security) (deflated 50%) adding: Microsoft.AspNetCore.Http.Features.dll (164 bytes security) (deflated 50%) adding: Microsoft.AspNetCore.HttpOverrides.dll (164 bytes security) (deflated 47%) adding: Microsoft.AspNetCore.Server.IISIntegration.dll (164 bytes security) (deflated 47%) adding: Microsoft.AspNetCore.Server.Kestrel.dll (164 bytes security) (deflated 62%) adding: Microsoft.AspNetCore.WebUtilities.dll (164 bytes security) (deflated 55%) adding: Microsoft.Extensions.Configuration.Abstractions.dll (164 bytes security) (deflated 48%) adding: Microsoft.Extensions.Configuration.dll (164 bytes security) (deflated 45%) adding: Microsoft.Extensions.Configuration.EnvironmentVariables.dll (164 bytes security) (deflated 47%) adding: Microsoft.Extensions.DependencyInjection.Abstractions.dll (164 bytes security) (deflated 55%) adding: Microsoft.Extensions.DependencyInjection.dll (164 bytes security) (deflated 50%) adding: Microsoft.Extensions.FileProviders.Abstractions.dll (164 bytes security) (deflated 46%) adding: Microsoft.Extensions.FileProviders.Physical.dll (164 bytes security) (deflated 46%) adding: Microsoft.Extensions.FileSystemGlobbing.dll (164 bytes security) (deflated 48%) adding: Microsoft.Extensions.Logging.Abstractions.dll (164 bytes security) (deflated 55%) adding: Microsoft.Extensions.Logging.dll (164 bytes security) (deflated 43%) adding: Microsoft.Extensions.ObjectPool.dll (164 bytes security) (deflated 45%) adding: Microsoft.Extensions.Options.dll (164 bytes security) (deflated 46%) adding: Microsoft.Extensions.PlatformAbstractions.dll (164 bytes security) (deflated 45%) adding: Microsoft.Extensions.Primitives.dll (164 bytes security) (deflated 49%) adding: Microsoft.Net.Http.Headers.dll (164 bytes security) (deflated 52%) adding: System.Diagnostics.Contracts.dll (164 bytes security) (deflated 46%) adding: System.Net.WebSockets.dll (164 bytes security) (deflated 47%) adding: System.Text.Encodings.Web.dll (164 bytes security) (deflated 57%) adding: web.config (164 bytes security) (deflated 39%) ~\dotnet-core-tutorial\site> cd ../
  2. Add a deployment manifest that points to the site archive.

    Example ~\dotnet-core-tutorial\aws-windows-deployment-manifest.json

    Copy
    { "manifestVersion": 1, "deployments": { "aspNetCoreWeb": [ { "name": "test-dotnet-core", "parameters": { "appBundle": "site.zip", "iisPath": "/", "iisWebSite": "Default Web Site" } } ] } }
  3. Use the zip command to create a source bundle named dotnet-core-tutorial.zip.

    Copy
    ~\dotnet-core-tutorial> zip dotnet-core-tutorial.zip site.zip aws-windows-deployment-manifest.json adding: site.zip (164 bytes security) (stored 0%) adding: aws-windows-deployment-manifest.json (164 bytes security) (deflated 50%)

Deploy Your Application

Deploy the source bundle to the Elastic Beanstalk environment that you created earlier.

Note

You can download the source bundle here: dotnet-core-tutorial-bundle-v1.zip

To deploy a source bundle

  1. Open the Elastic Beanstalk console.

  2. Navigate to the management page for your environment.

  3. Choose Upload and Deploy.

  4. Choose Browse and upload the source bundle.

  5. Choose Deploy.

  6. When the deployment completes, choose the site URL to open your website in a new tab.

The application simply writes Hello from ASP.NET Core! to the response and returns.

Launching an environment creates the following resources:

  • EC2 instance – An Amazon Elastic Compute Cloud (Amazon EC2) virtual machine configured to run web apps on the platform that you choose.

    Each platform runs a different set of software, configuration files, and scripts to support a specific language version, framework, web container, or combination thereof. Most platforms use either Apache or nginx as a reverse proxy that sits in front of your web app, forwards requests to it, serves static assets, and generates access and error logs.

  • Instance security group – An Amazon EC2 security group configured to allow ingress on port 80. This resource lets HTTP traffic from the load balancer reach the EC2 instance running your web app. By default, traffic is not allowed on other ports.

  • Load balancer – An Elastic Load Balancing load balancer configured to distribute requests to the instances running your application. A load balancer also eliminates the need to expose your instances directly to the Internet.

  • Load balancer security group – An Amazon EC2 security group configured to allow ingress on port 80. This resource lets HTTP traffic from the Internet reach the load balancer. By default, traffic is not allowed on other ports.

  • Auto Scaling group – An Auto Scaling group configured to replace an instance if it is terminated or becomes unavailable.

  • Amazon S3 bucket – A storage location for your source code, logs, and other artifacts that are created when you use Elastic Beanstalk.

  • Amazon CloudWatch alarms – Two Amazon CloudWatch alarms that monitor the load on the instances in your environment and are triggered if the load is too high or too low. When an alarm is triggered, your Auto Scaling group scales up or down in response.

  • AWS CloudFormation stack – Elastic Beanstalk uses AWS CloudFormation to launch the resources in your environment and propagate configuration changes. The resources are defined in a template that you can view in the AWS CloudFormation management console.

  • Domain name – A domain name that routes to your web app in the form subdomain.region.elasticbeanstalk.com.

All of these resources are managed by Elastic Beanstalk. When you terminate your environment, Elastic Beanstalk terminates all of the resources that it contains.

Note

The S3 bucket that Elastic Beanstalk creates is shared between environments and is not deleted during environment termination. For more information, see Using Elastic Beanstalk with Amazon S3.

Clean Up

When you finish working with Elastic Beanstalk, you can terminate your Windows Server environment.

To terminate your Elastic Beanstalk environment

  1. Open the Elastic Beanstalk console.

  2. Navigate to the management page for your environment.

  3. Choose Actions, and then choose Terminate Environment.

Elastic Beanstalk terminates all AWS resources associated with your environment, including EC2 instances, the load balancer, security groups, Amazon CloudWatch alarms, etc.

Next Steps

As you continue to develop your application, you'll probably want to manage environments and deploy your application without manually creating a .zip file and uploading it to the Elastic Beanstalk console. The Elastic Beanstalk Command Line Interface (EB CLI) provides easy-to-use commands for creating, configuring, and deploying applications to Elastic Beanstalk environments from the command line.

For development and testing, you might want to use Elastic Beanstalk's functionality for adding a managed DB instance directly to your environment. For instructions on setting up a database inside your environment, see Configuring Databases with Elastic Beanstalk.

Finally, if you plan on using your application in a production environment, configure a custom domain name for your environment and enable HTTPS for secure connections.