AWS Elastic Beanstalk
Developer Guide

Deploying an ASP.NET Core Application with AWS Elastic Beanstalk

In this tutorial, you will walk through the process of building a new ASP.NET Core application and deploying it to Elastic Beanstalk.

First, you will use the .NET Core SDK's dotnet command line tool to generate a basic .NET Core command line application, install dependencies, compile code, and run applications locally. Next, you will create the default Program.cs class, and add an ASP.NET Startup.cs class and configuration files to make an application that serves HTTP requests with ASP.NET and IIS.

Finally, 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 a site archive to an application source bundle with a deployment manifest. The dotnet publish command generates compiled classes and dependencies that you can bundle with a web.config file to create a site archive. 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.

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

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

Prerequisites

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

Requirements

  • .NET Core (x64) 1.0.1, 2.0.0, or later

To install the .NET Core SDK

  1. Download the installer from microsoft.com/net/core. Choose Windows. Choose Download .NET SDK.

  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.

    1. Press the Windows key, and then type environment variables.

    2. Choose Edit environment variables for your account.

    3. Choose PATH, and then choose Edit.

    4. Add paths to the Variable value field, separated by semicolons. For example: C:\item1\path;C:\item2\path

    5. Choose OK twice to apply the new settings.

    6. Close any running command prompts and reopen command prompt.

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

    > zip -h 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 window and navigate to your user folder.

    > cd %USERPROFILE%
  2. Use the dotnet new command to generate a new .NET Core project.

    C:\Users\username> dotnet new console -o dotnet-core-tutorial Content generation time: 65.0152 ms The template "Console Application" created successfully. C:\Users\username> cd dotnet-core-tutorial
  3. Use the dotnet restore command to install dependencies.

    C:\Users\username\dotnet-core-tutorial> dotnet restore Restoring packages for C:\Users\username\dotnet-core-tutorial\dotnet-core-tutorial.csproj... Generating MSBuild file C:\Users\username\dotnet-core-tutorial\obj\dotnet-core-tutorial.csproj.nuget.g.props. Generating MSBuild file C:\Users\username\dotnet-core-tutorial\obj\dotnet-core-tutorial.csproj.nuget.g.targets. Writing lock file to disk. Path: C:\Users\username\dotnet-core-tutorial\obj\project.assets.json Restore completed in 1.25 sec for C:\Users\username\dotnet-core-tutorial\dotnet-core-tutorial.csproj. NuGet Config files used: C:\Users\username\AppData\Roaming\NuGet\NuGet.Config C:\Program Files (x86)\NuGet\Config\Microsoft.VisualStudio.Offline.config Feeds used: https://api.nuget.org/v3/index.json C:\Program Files (x86)\Microsoft SDKs\NuGetPackages\
  4. Use the dotnet run command to build and run the application locally.

    C:\Users\username\dotnet-core-tutorial> dotnet run Hello World!

Launch an Elastic Beanstalk Environment

Use the AWS Management Console to launch an Elastic Beanstalk environment. For this example, you will launch with a .NET platform. 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 using this preconfigured link: console.aws.amazon.com/elasticbeanstalk/home#/newApplication?applicationName=tutorials&environmentType=LoadBalanced&instanceType=t2.micro

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

  3. For Application code, choose Sample application.

  4. Choose Review and launch.

  5. Review the available options. When you're satisfied with them, 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 Amazon EC2 instances in your Elastic Beanstalk environment.

The source code examples to follow are available here: dotnet-core-tutorial-source.zip

To add ASP.NET and IIS support to your code

  1. Copy Program.cs to your application directory to run as a web host builder.

    Example c:\users\username\dotnet-core-tutorial\Program.cs

    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 Startup.cs to run an ASP.NET website.

    Example c:\users\username\dotnet-core-tutorial\Startup.cs

    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 the web.config file to configure the IIS server.

    Example c:\users\username\dotnet-core-tutorial\web.config

    <?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. Add dotnet-core-tutorial.csproj, which includes IIS middleware and includes the web.config file from the output of dotnet publish.

    Note

    The following example was developed using .NET Core Runtime 2.0.5. You might need to modify the TargetFramework or the Version attribute values in the PackageReference elements to match the version of .NET Core Runtime that you are using in your custom projects..

    Example c:\users\username\dotnet-core-tutorial\dotnet-core-tutorial.csproj

    <Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <OutputType>Exe</OutputType> <TargetFramework>netcoreapp2.0</TargetFramework> </PropertyGroup> <ItemGroup> <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel" Version="2.0.1" /> </ItemGroup> <ItemGroup> <PackageReference Include="Microsoft.AspNetCore.Server.IISIntegration" Version="2.0.1" /> </ItemGroup> <ItemGroup> <None Include="web.config" CopyToPublishDirectory="Always" /> </ItemGroup> </Project>

Next, 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 dotnet-core-tutorial.csproj.

To build your website

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

    C:\users\username\dotnet-core-tutorial> dotnet publish -o site

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

To create a source bundle

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

    C:\users\username\dotnet-core-tutorial> cd site C:\users\username\dotnet-core-tutorial\site> zip ../site.zip * adding: dotnet-core-tutorial.deps.json (144 bytes security) (deflated 83%) adding: dotnet-core-tutorial.dll (144 bytes security) (deflated 60%) adding: dotnet-core-tutorial.pdb (144 bytes security) (deflated 29%) adding: dotnet-core-tutorial.runtimeconfig.json (144 bytes security) (deflated 27%) adding: Microsoft.AspNetCore.Authentication.Abstractions.dll (144 bytes security) (deflated 50%) adding: Microsoft.AspNetCore.Authentication.Core.dll (144 bytes security) (deflated 52%) adding: Microsoft.AspNetCore.Hosting.Abstractions.dll (144 bytes security) (deflated 47%) adding: Microsoft.AspNetCore.Hosting.dll (144 bytes security) (deflated 60%) adding: Microsoft.AspNetCore.Hosting.Server.Abstractions.dll (144 bytes security) (deflated 44%) adding: Microsoft.AspNetCore.Http.Abstractions.dll (144 bytes security) (deflated 54%) adding: Microsoft.AspNetCore.Http.dll (144 bytes security) (deflated 54%) adding: Microsoft.AspNetCore.Http.Extensions.dll (144 bytes security) (deflated 50%) adding: Microsoft.AspNetCore.Http.Features.dll (144 bytes security) (deflated 51%) adding: Microsoft.AspNetCore.HttpOverrides.dll (144 bytes security) (deflated 49%) adding: Microsoft.AspNetCore.Server.IISIntegration.dll (144 bytes security) (deflated 46%) adding: Microsoft.AspNetCore.Server.Kestrel.Core.dll (144 bytes security) (deflated 63%) adding: Microsoft.AspNetCore.Server.Kestrel.dll (144 bytes security) (deflated 44%) adding: Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.dll (144 bytes security) (deflated 54%) adding: Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv.dll (144 bytes security) (deflated 54%) adding: Microsoft.AspNetCore.WebUtilities.dll (144 bytes security) (deflated 55%) adding: Microsoft.Extensions.Configuration.Abstractions.dll (144 bytes security) (deflated 47%) adding: Microsoft.Extensions.Configuration.dll (144 bytes security) (deflated 45%) adding: Microsoft.Extensions.Configuration.EnvironmentVariables.dll (144 bytes security) (deflated 46%) adding: Microsoft.Extensions.Configuration.FileExtensions.dll (144 bytes security) (deflated 46%) adding: Microsoft.Extensions.DependencyInjection.Abstractions.dll (144 bytes security) (deflated 54%) adding: Microsoft.Extensions.DependencyInjection.dll (144 bytes security) (deflated 51%) adding: Microsoft.Extensions.FileProviders.Abstractions.dll (144 bytes security) (deflated 45%) adding: Microsoft.Extensions.FileProviders.Physical.dll (144 bytes security) (deflated 46%) adding: Microsoft.Extensions.FileSystemGlobbing.dll (144 bytes security) (deflated 49%) adding: Microsoft.Extensions.Hosting.Abstractions.dll (144 bytes security) (deflated 45%) adding: Microsoft.Extensions.Logging.Abstractions.dll (144 bytes security) (deflated 55%) adding: Microsoft.Extensions.Logging.dll (144 bytes security) (deflated 48%) adding: Microsoft.Extensions.ObjectPool.dll (144 bytes security) (deflated 45%) adding: Microsoft.Extensions.Options.dll (144 bytes security) (deflated 48%) adding: Microsoft.Extensions.Primitives.dll (144 bytes security) (deflated 49%) adding: Microsoft.Net.Http.Headers.dll (144 bytes security) (deflated 53%) adding: runtimes/ (144 bytes security) (stored 0%) adding: System.Runtime.CompilerServices.Unsafe.dll (144 bytes security) (deflated 44%) adding: System.Text.Encodings.Web.dll (144 bytes security) (deflated 57%) adding: web.config (144 bytes security) (deflated 41%) C:\users\username\dotnet-core-tutorial\site> cd ../
  2. Add a deployment manifest that points to the site archive.

    Example c:\users\username\dotnet-core-tutorial\aws-windows-deployment-manifest.json

    { "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.

    C:\users\username\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.

You can download the source bundle here: dotnet-core-tutorial-bundle.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 Choose File and use the dialog box to select 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 specific 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 isn't 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 isn't 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 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 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 the resources that it contains.

Note

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

Cleanup

When you finish working with Elastic Beanstalk, you can terminate your environment. Elastic Beanstalk terminates all AWS resources associated with your environment, such as Amazon EC2 instances, database instances, load balancers, security groups, and alarms.

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.

  4. In the Confirm Termination dialog box, type the environment name, and then choose Terminate.

With Elastic Beanstalk, you can easily create a new environment for your application at any time.

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.

If you use Visual Studio to develop your application, you can also use the AWS Toolkit for Visual Studio to deploy changed, manage your Elastic Beanstalk environments, and manage other AWS resources. See The AWS Toolkit for Visual Studio for more information.

For developing and testing, you might want to use the Elastic Beanstalk functionality for adding a managed DB instance directly to your environment. For instructions on setting up a database inside your environment, see Adding a Database to Your Elastic Beanstalk Environment.

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