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 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.zip

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

Prerequisites

This tutorial uses the .NET Core SDK version 1.0.1 (x64) 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. Choose Windows, then under Select your environment choose Command line / other. Choose Download .NET Core 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.

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

    > 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 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!

The default application prints Hello World! to the console and exits. Before you deploy the application to Elastic Beanstalk, you 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 using 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 Application code, choose Sample application.

  4. Choose Review and launch.

  5. Review all 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 EC2 instances in your Elastic Beanstalk environment.

Note

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

To add ASP.NET and IIS support to your code

  1. Update Program.cs to run 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 a Startup.cs file 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 a 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. Update dotnet-core-tutorial.csproj to include IIS middleware and include the web.config file in the output of dotnet publish.

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

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

Next, you 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 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.

    C:\users\username\dotnet-core-tutorial> cd site
    C:\users\username\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.Diagnostics.StackTrace.dll (164 bytes security) (deflated 45%)
      adding: System.Net.WebSockets.dll (164 bytes security) (deflated 47%)
      adding: System.Runtime.CompilerServices.Unsafe.dll (164 bytes security) (deflated 42%)
      adding: System.Text.Encodings.Web.dll (164 bytes security) (deflated 57%)
      adding: web.config (164 bytes security) (deflated 39%)
    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 earlier.

Note

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

In addition, you can terminate database resources that you created outside of your Elastic Beanstalk environment. When you terminate an Amazon RDS database instance, you can take a snapshot and restore the data to another instance later.

To terminate your RDS DB instance

  1. Open the Amazon RDS console.

  2. Choose Instances.

  3. Choose your DB instance.

  4. Choose Instance Actions, and then choose Delete.

  5. Choose whether to create a snapshot, and then choose Delete.

To delete a DynamoDB table

  1. Open the Tables page in the DynamoDB console.

  2. Select a table.

  3. Choose Actions, and then choose Delete table.

  4. Choose Delete.

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 developing 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 to use your application in a production environment, configure a custom domain name for your environment and enable HTTPS for secure connections.