# Using the Elastic Beanstalk .NET Windows platform
This topic describes how to configure, build, and run your ASP.NET and .NET Core Windows web applications on Elastic Beanstalk.
AWS Elastic Beanstalk supports a number of platforms for different versions of the .NET programming framework and Windows Server. See [.NET on Windows Server with IIS](https://docs.aws.amazon.com/elasticbeanstalk/latest/platforms/platforms-supported.html#platforms-supported.net) in the *AWS Elastic Beanstalk Platforms* document for a full list.
Elastic Beanstalk provides [configuration options](command-options.md) that you can use to customize the software that runs on the EC2 instances in your Elastic Beanstalk environment. You can configure environment variables needed by your application, enable log rotation to Amazon S3, and set .NET framework settings.
Configuration options are available in the Elastic Beanstalk console for [modifying the configuration of a running environment](environment-configuration-methods-after.md). To avoid losing your environment's configuration when you terminate it, you can use [saved configurations](environment-configuration-savedconfig.md) to save your settings and later apply them to another environment.
To save settings in your source code, you can include [configuration files](ebextensions.md). Settings in configuration files are applied every time you create an environment or deploy your application. You can also use configuration files to install packages, run scripts, and perform other instance customization operations during deployments.
Settings applied in the Elastic Beanstalk console override the same settings in configuration files, if they exist. This lets you have default settings in configuration files, and override them with environment-specific settings in the console. For more information about precedence, and other methods of changing settings, see [Configuration options](command-options.md).
## Configuring your .NET environment in the Elastic Beanstalk console
You can use the Elastic Beanstalk console to enable log rotation to Amazon S3, configure variables that your application can read from the environment, and change .NET framework settings.
**To configure your .NET environment in the Elastic Beanstalk console**
1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region.
1. In the navigation pane, choose **Environments**, and then choose the name of your environment from the list.
1. In the navigation pane, choose **Configuration**.
1. In the **Updates, monitoring, and logging** configuration category, choose **Edit**.
### Container options
+ **Target .NET runtime** – Set to `2.0` to run CLR v2.
+ **Enable 32-bit applications** – Set to `True` to run 32-bit applications.
### Log options
The Log Options section has two settings:
+ **Instance profile** – Specifies the instance profile that has permission to access the Amazon S3 bucket associated with your application.
+ **Enable log file rotation to Amazon S3** – Specifies whether log files for your application's Amazon EC2 instances are copied to the Amazon S3 bucket associated with your application.
### Environment properties
The **Environment Properties** section lets you specify environment configuration settings on the Amazon EC2 instances that are running your application. These settings are passed in as key-value pairs to the application. Use `System.GetEnvironmentVariable` to read them. Identical keys can exist in both `web.config` and as environment properties. Use the `System.Configuration` namespace to read values from `web.config`.
```
NameValueCollection appConfig = ConfigurationManager.AppSettings;
string endpoint = appConfig["API_ENDPOINT"];
```
See [Environment variables and other software settings](environments-cfg-softwaresettings.md) for more information.
## The aws:elasticbeanstalk:container:dotnet:apppool namespace
You can use a [configuration file](ebextensions.md) to set configuration options and perform other instance configuration tasks during deployments. Configuration options can be [platform specific](command-options-specific.md) or apply to [all platforms](command-options-general.md) in the Elastic Beanstalk service as a whole. Configuration options are organized into *namespaces*.
The .NET platform defines options in the `aws:elasticbeanstalk:container:dotnet:apppool` namespace that you can use to configure the .NET runtime.
The following example configuration file shows settings for each of the options available in this namespace:
**Example .ebextensions/dotnet-settings.config**
```
option_settings:
aws:elasticbeanstalk:container:dotnet:apppool:
Target Runtime: 2.0
Enable 32-bit Applications: True
```
Elastic Beanstalk provides many configuration options for customizing your environment. In addition to configuration files, you can also set configuration options using the console, saved configurations, the EB CLI, or the AWS CLI. See [Configuration options](command-options.md) for more information.
# Migrating across major versions of the Elastic Beanstalk Windows server platform
AWS Elastic Beanstalk has had several major versions of its Windows Server platform. This page covers the main improvements for each major version, and what to consider before you migrate to a later version.
The Windows Server platform is currently at version 2 (v2). If your application uses any Windows Server platform version earlier than v2, we recommend that you migrate to v2.
## What's new in major versions of the Windows server platform
### Windows server platform V2
Version 2 (v2) of the Elastic Beanstalk Windows Server platform was [released in February 2019](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2019-02-21-windows-v2.html). V2 brings the behavior of the Windows Server platform closer to that of the Elastic Beanstalk Linux-based platforms in several important ways. V2 is fully backward compatible with v1, making migration from v1 easy.
The Windows Server platform now supports the following:
+ *Versioning* – Each release gets a new version number, and you can refer to past versions (that are still available to you) when creating and managing environments.
+ *Enhanced health* – For details, see [Enhanced health reporting and monitoring in Elastic Beanstalk](health-enhanced.md).
+ *Immutable* and *Rolling with an Additional Batch* deployments – For details about deployment policies, see [Deploying applications to Elastic Beanstalk environments](using-features.deploy-existing-version.md).
+ *Immutable updates* – For details about update types, see [Configuration changes](environments-updating.md).
+ *Managed platform updates* – For details, see [Managed platform updates](environment-platform-update-managed.md).
**Note**
The new deployment and update features depend on enhanced health. Enable enhanced health to use them. For details, see [Enabling Elastic Beanstalk enhanced health reporting](health-enhanced-enable.md).
### Windows server platform V1
Version 1.0.0 (v1) of the Elastic Beanstalk Windows Server platform was released in October 2015. This version changes the order in which Elastic Beanstalk processes commands in [configuration files](ebextensions.md) during environment creation and updates.
Previous platform versions don't have a version number in the solution stack name:
+ 64bit Windows Server 2012 R2 running IIS 8.5
+ 64bit Windows Server Core 2012 R2 running IIS 8.5
+ 64bit Windows Server 2012 running IIS 8
+ 64bit Windows Server 2008 R2 running IIS 7.5
In earlier versions, the processing order for configuration files is inconsistent. During environment creation, `Container Commands` run after the application source is deployed to IIS. During a deployment to a running environment, container commands run before the new version is deployed. During a scale up, configuration files are not processed at all.
In addition to this, IIS starts up before container commands run. This behavior has led some customers to implement workarounds in container commands, pausing the IIS server before commands run, and starting it again after they complete.
Version 1 fixes the inconsistency and brings the behavior of the Windows Server platform closer to that of the Elastic Beanstalk Linux-based platforms. In the v1 platform, Elastic Beanstalk always runs container commands before starting the IIS server.
The v1 platform solution stacks have a `v1` after the Windows Server version:
+ 64bit Windows Server 2012 R2 v1.1.0 running IIS 8.5
+ 64bit Windows Server Core 2012 R2 v1.1.0 running IIS 8.5
+ 64bit Windows Server 2012 v1.1.0 running IIS 8
+ 64bit Windows Server 2008 R2 v1.1.0 running IIS 7.5
Additionally, the v1 platform extracts the contents of your application source bundle to `C:\staging\` before running container commands. After container commands complete, the contents of this folder are compressed into a .zip file and deployed to IIS. This workflow allows you to modify the contents of your application source bundle with commands or a script before deployment.
## Migrating from earlier major versions of the Windows server platform
Read this section for migration considerations before you update your environment. To update your environment's platform to a newer version, see [Updating your Elastic Beanstalk environment's platform version](using-features.platform.upgrade.md).
### From V1 to V2
The Windows Server platform v2 doesn't support .NET Core 1.x and 2.0. If you're migrating your application from Windows Server v1 to v2, and your application uses one of these .NET Core versions, update your application to a .NET Core version that v2 supports. For a list of supported versions, see [.NET on Windows Server with IIS](https://docs.aws.amazon.com/elasticbeanstalk/latest/platforms/platforms-supported.html#platforms-supported.net) in the *AWS Elastic Beanstalk Platforms*.
If your application uses a custom Amazon Machine Image (AMI), create a new custom AMI based on a Windows Server platform v2 AMI. To learn more, see [Using a custom Amazon machine image (AMI) in your Elastic Beanstalk environment](using-features.customenv.md).
**Note**
The deployment and update features that are new to Windows Server v2 depend on enhanced health. When you migrate an environment to v2, enhanced health is disabled. Enable it to use these features. For details, see [Enabling Elastic Beanstalk enhanced health reporting](health-enhanced-enable.md).
### From pre-V1
In addition to considerations for migrating from v1, if you're migrating your application from a Windows Server solution stack that's earlier than v1, and you currently use container commands, remove any commands that you added to work around the processing inconsistencies when you migrate to a newer version. Starting with v1, container commands are guaranteed to run completely before the application source that is deployed and before IIS starts. This enables you to make any changes to the source in `C:\staging` and modify IIS configuration files during this step without issue.
For example, you can use the AWS CLI to download a DLL file to your application source from Amazon S3:
`.ebextensions\copy-dll.config`
```
container_commands:
copy-dll:
command: aws s3 cp s3://amzn-s3-demo-bucket/dlls/large-dll.dll .\lib\
```
For more information on using configuration files, see [Advanced environment customization with configuration files (`.ebextensions`)](ebextensions.md).
# Running multiple applications and ASP.NET core applications with a deployment manifest
You can use a deployment manifest to tell Elastic Beanstalk how to deploy your application. By using this method, you don't need to use `MSDeploy` to generate a source bundle for a single ASP.NET application that runs at the root path of your website. Rather, you can use a manifest file to run multiple applications at different paths. Or, alternatively, you can tell Elastic Beanstalk to deploy and run the app with ASP.NET Core. You can also use a deployment manifest to configure an application pool where to run your applications.
Deployment manifests add support for [.NET Core applications](#dotnet-manifest-dotnetcore) to Elastic Beanstalk. You can deploy a .NET Framework application without a deployment manifest. However, .NET Core applications require a deployment manifest to run on Elastic Beanstalk. When you use a deployment manifest, you create a site archive for each application, and then bundle the site archives in a second ZIP archive that contains the deployment manifest.
Deployment manifests also add the ability to [run multiple applications at different paths](#dotnet-manifest-multiapp). A deployment manifest defines an array of deployment targets, each with a site archive and a path at which IIS should run it. For example, you could run a web API at the `/api` path to serve asynchronous requests, and a web app at the root path that consumes the API.
You can use a deployment manifest to [configure IIS websites with custom bindings and physical paths](#dotnet-manifest-websites). This allows you to set up websites that listen on specific ports or host names before deploying your applications.
You can also use a deployment manifest to [run multiple applications using application pools in IIS or Kestrel](#dotnet-manifest-apppool). You can configure an application pool to restart your applications periodically, run 32-bit applications, or use a specific version of the .NET Framework runtime.
For full customization, you can [write your own deployment scripts](#dotnet-manifest-custom) in Windows PowerShell and tell Elastic Beanstalk which scripts to run to install, uninstall, and restart your application.
Deployment manifests and related features require a Windows Server platform [version 1.2.0 or newer](dotnet-v2migration.md).
For detailed information about all available configuration options, properties, and advanced features like skipping IIS resets, see the [deployment manifest schema reference](dotnet-manifest-schema.md).
**Topics**
+ [.NET core apps](#dotnet-manifest-dotnetcore)
+ [Run multiple applications](#dotnet-manifest-multiapp)
+ [Configure IIS websites](#dotnet-manifest-websites)
+ [Using Application Request Routing (ARR)](#dotnet-manifest-arr)
+ [Configure application pools](#dotnet-manifest-apppool)
+ [Define custom deployments](#dotnet-manifest-custom)
+ [Deployment manifest schema reference](dotnet-manifest-schema.md)
## .NET core apps
You can use a deployment manifest to run .NET Core applications on Elastic Beanstalk. .NET Core is a cross-platform version of .NET that comes with a command line tool (`dotnet`). You can use it to generate an application, run it locally, and prepare it for publishing.
To run a .NET Core application on Elastic Beanstalk, you can run `dotnet publish` and package the output in a ZIP archive, not including any containing directories. Place the site archive in a source bundle with a deployment manifest with a deployment target of type `aspNetCoreWeb`.
The following deployment manifest runs a .NET Core application from a site archive named `dotnet-core-app.zip` at the root path.
**Example aws-windows-deployment-manifest.json - .NET core**
```
{
"manifestVersion": 1,
"deployments": {
"aspNetCoreWeb": [
{
"name": "my-dotnet-core-app",
"parameters": {
"archive": "dotnet-core-app.zip",
"iisPath": "/"
}
}
]
}
}
```
Bundle the manifest and site archive in a ZIP archive to create a source bundle.
**Example dotnet-core-bundle.zip**
```
.
|-- aws-windows-deployment-manifest.json
`-- dotnet-core-app.zip
```
The site archive contains the compiled application code, dependencies, and `web.config` file.
**Example dotnet-core-app.zip**
```
.
|-- Microsoft.AspNetCore.Hosting.Abstractions.dll
|-- Microsoft.AspNetCore.Hosting.Server.Abstractions.dll
|-- Microsoft.AspNetCore.Hosting.dll
|-- Microsoft.AspNetCore.Http.Abstractions.dll
|-- Microsoft.AspNetCore.Http.Extensions.dll
|-- Microsoft.AspNetCore.Http.Features.dll
|-- Microsoft.AspNetCore.Http.dll
|-- Microsoft.AspNetCore.HttpOverrides.dll
|-- Microsoft.AspNetCore.Server.IISIntegration.dll
|-- Microsoft.AspNetCore.Server.Kestrel.dll
|-- Microsoft.AspNetCore.WebUtilities.dll
|-- Microsoft.Extensions.Configuration.Abstractions.dll
|-- Microsoft.Extensions.Configuration.EnvironmentVariables.dll
|-- Microsoft.Extensions.Configuration.dll
|-- Microsoft.Extensions.DependencyInjection.Abstractions.dll
|-- Microsoft.Extensions.DependencyInjection.dll
|-- Microsoft.Extensions.FileProviders.Abstractions.dll
|-- Microsoft.Extensions.FileProviders.Physical.dll
|-- Microsoft.Extensions.FileSystemGlobbing.dll
|-- Microsoft.Extensions.Logging.Abstractions.dll
|-- Microsoft.Extensions.Logging.dll
|-- Microsoft.Extensions.ObjectPool.dll
|-- Microsoft.Extensions.Options.dll
|-- Microsoft.Extensions.PlatformAbstractions.dll
|-- Microsoft.Extensions.Primitives.dll
|-- Microsoft.Net.Http.Headers.dll
|-- System.Diagnostics.Contracts.dll
|-- System.Net.WebSockets.dll
|-- System.Text.Encodings.Web.dll
|-- dotnet-core-app.deps.json
|-- dotnet-core-app.dll
|-- dotnet-core-app.pdb
|-- dotnet-core-app.runtimeconfig.json
`-- web.config
```
## Run multiple applications
You can run multiple applications with a deployment manifest by defining multiple deployment targets.
The following deployment manifest configures two .NET Core applications. The `WebApiSampleApp` application implements a simple web API and serves asynchronous requests at the `/api` path. The `DotNetSampleApp` application is a web application that serves requests at the root path.
**Example aws-windows-deployment-manifest.json - multiple apps**
```
{
"manifestVersion": 1,
"deployments": {
"aspNetCoreWeb": [
{
"name": "WebAPISample",
"parameters": {
"appBundle": "WebApiSampleApp.zip",
"iisPath": "/api"
}
},
{
"name": "DotNetSample",
"parameters": {
"appBundle": "DotNetSampleApp.zip",
"iisPath": "/"
}
}
]
}
}
```
A sample application with multiple applications is available here:
+ **Deployable source bundle** - [dotnet-multiapp-sample-bundle-v2.zip](samples/dotnet-multiapp-sample-bundle-v2.zip)
+ **Source code** - [dotnet-multiapp-sample-source-v2.zip](samples/dotnet-multiapp-sample-source-v2.zip)
## Configure IIS websites
You can configure IIS websites with custom bindings and physical paths using the deployment manifest. This is useful when you need to set up websites that listen on specific ports, use custom host names, or serve content from specific directories.
The following deployment manifest configures a custom IIS website that listens on HTTP with a specific port number and a custom physical path:
**Example aws-windows-deployment-manifest.json - IIS website configuration**
```
{
"manifestVersion": 1,
"iisConfig": {
"websites": [
{
"name": "MyCustomSite",
"physicalPath": "C:\inetpub\wwwroot\mysite",
"bindings": [
{
"protocol": "http",
"port": 8080,
"hostName": "mysite.local"
}
]
}
]
},
"deployments": {
"aspNetCoreWeb": [
{
"name": "my-dotnet-core-app",
"parameters": {
"appBundle": "dotnet-core-app.zip",
"iisWebSite": "MyCustomSite",
"iisPath": "/"
}
}
]
}
}
```
In this example:
+ A website named "MyCustomSite" is created with a custom physical path
+ The website has an HTTP binding on port 8080 with a specific host name
+ The ASP.NET Core application is deployed to this custom website using the `iisWebSite` parameter
## Using Application Request Routing (ARR)
Application Request Routing (ARR) and URL Rewrite modules are pre-installed and available in Elastic Beanstalk Windows AMIs. These modules enable advanced routing scenarios and URL manipulation through IIS configuration using ebextensions or application configuration.
The following example shows a simple deployment manifest that configures a website with a custom port, combined with an ebextensions configuration that sets up basic ARR routing:
**Example aws-windows-deployment-manifest.json - Simple ARR setup**
```
{
"manifestVersion": 1,
"iisConfig": {
"websites": [
{
"name": "ARRSite",
"physicalPath": "C:\\inetpub\\wwwroot\\arrsite",
"bindings": [
{
"protocol": "http",
"port": 8080,
"hostName": "localhost"
}
]
}
]
},
"deployments": {
"aspNetCoreWeb": [
{
"name": "BackendApp",
"parameters": {
"appBundle": "backend-app.zip",
"iisWebSite": "ARRSite",
"iisPath": "/backend"
}
}
]
}
}
```
ARR configuration is done through ebextensions. The following configuration sets up basic ARR routing rules:
**Example .ebextensions/arr-config.config - Basic ARR configuration**
```
files:
"C:\\temp\\configure-arr.ps1":
content: |
# Enable ARR proxy at server level
Set-WebConfigurationProperty -PSPath 'MACHINE/WEBROOT/APPHOST' -Filter 'system.webServer/proxy' -Name 'enabled' -Value 'True'
# Clear any existing global rules to avoid conflicts
Clear-WebConfiguration -PSPath 'MACHINE/WEBROOT/APPHOST' -Filter 'system.webServer/rewrite/globalRules'
# Add global rule to route all requests to backend
Add-WebConfigurationProperty -PSPath 'MACHINE/WEBROOT/APPHOST' `
-Filter 'system.webServer/rewrite/globalRules' `
-Name '.' `
-Value @{
name = 'Route_to_Backend'
stopProcessing = 'True'
match = @{ url = '^(?!backend/)(.*)' }
action = @{
type = 'Rewrite'
url = 'http://localhost:8080/backend/{R:1}'
}
}
container_commands:
01_configure_arr:
command: powershell -ExecutionPolicy Bypass -File "C:\\temp\\configure-arr.ps1"
waitAfterCompletion: 0
```
This configuration creates a website on port 8080 and sets up ARR to route all incoming requests to the backend application running on that site.
## Configure application pools
You can support multiple applications in your Windows environment. Two approaches are available:
+ You can use the out-of-process hosting model with the Kestrel web server. With this model, you configure multiple applications to run in one application pool.
+ You can use the in-process hosting model.With this model, you use multiple application pools to run multiple applications with only one application in each pool. If you're using IIS server and need to run multiple applications, you must use this approach.
To configure Kestrel to run multiple applications in one application pool, add `hostingModel="OutofProcess"` in the `web.config` file. Consider the following examples.
**Example web.config - for Kestrel out-of-process hosting model**
```
```
**Example aws-windows-deployment-manifest.json - multiple applications**
```
{
"manifestVersion": 1,
"deployments": {"msDeploy": [
{"name": "Web-app1",
"parameters": {"archive": "site1.zip",
"iisPath": "/"
}
},
{"name": "Web-app2",
"parameters": {"archive": "site2.zip",
"iisPath": "/app2"
}
}
]
}
}
```
IIS doesn't support multiple applications in one application pool because it uses the in-process hosting model. Therefore, you need to configure multiple applications by assigning each application to one application pool. In other words, assign only one application to one application pool.
You can configure IIS to use different application pools in the `aws-windows-deployment-manifest.json` file. Make the following updates as you refer to the next example file:
+ Add an `iisConfig` section that includes a subsection called `appPools`.
+ In the `appPools` block, list the application pools.
+ In the `deployments` section, define a `parameters` section for each application.
+ For each application the `parameters` section specifies an archive, a path to run it, and an `appPool` in which to run.
The following deployment manifest configures two application pools that restart their application every 10 minutes. They also attach their applications to a .NET Framework web application that runs at the path specified.
**Example aws-windows-deployment-manifest.json - one application per application pool**
```
{
"manifestVersion": 1,
"iisConfig": {"appPools": [
{"name": "MyFirstPool",
"recycling": {"regularTimeInterval": 10}
},
{"name": "MySecondPool",
"recycling": {"regularTimeInterval": 10}
}
]
},
"deployments": {"msDeploy": [
{"name": "Web-app1",
"parameters": {
"archive": "site1.zip",
"iisPath": "/",
"appPool": "MyFirstPool"
}
},
{"name": "Web-app2",
"parameters": {
"archive": "site2.zip",
"iisPath": "/app2",
"appPool": "MySecondPool"
}
}
]
}
}
```
## Define custom deployments
For even more control, you can completely customize an application deployment by defining a *custom deployment*.
This deployment manifest instructs Elastic Beanstalk to execute PowerShell scripts in 32-bit mode. It specifies three scripts: an `install` script (`siteInstall.ps1`) that runs during instance launch and deployments, an `uninstall` script (`siteUninstall.ps1`) that executes before installing new versions during deployments, and a `restart` script (`siteRestart.ps1`) that runs when you select [Restart App Server](environments-dashboard-actions.md) in the AWS management console.
**Example aws-windows-deployment-manifest.json - custom deployment**
```
{
"manifestVersion": 1,
"deployments": {
"custom": [
{
"name": "Custom site",
"architecture" : 32,
"scripts": {
"install": {
"file": "siteInstall.ps1"
},
"restart": {
"file": "siteRestart.ps1"
},
"uninstall": {
"file": "siteUninstall.ps1"
}
}
}
]
}
}
```
Include any artifacts required to run the application in your source bundle with the manifest and scripts.
**Example Custom-site-bundle.zip**
```
.
|-- aws-windows-deployment-manifest.json
|-- siteInstall.ps1
|-- siteRestart.ps1
|-- siteUninstall.ps1
`-- site-contents.zip
```
# Deployment manifest schema reference
The deployment manifest is a JSON file that defines how Elastic Beanstalk should deploy and configure your Windows applications. This section provides a comprehensive reference for all supported properties and configuration options in the manifest schema.
## Manifest structure
The deployment manifest follows a specific JSON schema with the following top-level structure:
**Example Basic manifest structure**
```
{
"manifestVersion": 1,
"skipIISReset": false,
"iisConfig": {
"websites": [...],
"appPools": [...]
},
"deployments": {
"msDeploy": [...],
"aspNetCoreWeb": [...],
"custom": [...]
}
}
```
### Top-level properties
`manifestVersion` (required)
*Type:* Number
*Default:* 1
*Valid values:* 1
Specifies the version of the manifest schema. Currently, only version 1 is supported.
`skipIISReset` (optional)
*Type:* Boolean
*Default:* false
Controls whether IIS is reset during application deployments. This flag affects both `msDeploy` and `aspNetCoreWeb` deployment types.
*Behavior:*
+ *Not specified or `false` (default):* IIS resets are performed during install, uninstall, and update operations. This is the traditional behavior.
+ *`true`:* IIS resets are skipped during deployment operations.
*Benefits:*
+ *Reduced downtime* – Applications experience shorter service interruptions during deployments.
+ *Faster deployments* – Eliminates the time required for IIS to fully restart and reinitialize.
When using `skipIISReset`, the [RestartAppServer](https://docs.aws.amazon.com/elasticbeanstalk/latest/api/API_RestartAppServer.html) operation performs an IIS reset regardless of this flag setting.
*Example:*
```
{
"manifestVersion": 1,
"skipIISReset": true,
"deployments": {
"aspNetCoreWeb": [
{
"name": "my-dotnet-core-app",
"parameters": {
"archive": "dotnet-core-app.zip",
"iisPath": "/"
}
}
]
}
}
```
`deployments` (required)
*Type:* Object
Contains the deployment configurations for your applications. This object can include `msDeploy`, `aspNetCoreWeb`, and `custom` deployment types.
`iisConfig` (optional)
*Type:* Object
Defines IIS configuration settings to apply before deploying applications. Supports both website and application pool configuration.
## IIS configuration
The `iisConfig` section allows you to configure IIS settings before deploying your applications. This includes setting up application pools with specific configurations and configuring IIS websites with custom bindings.
### IIS websites
IIS websites allow you to configure custom website settings including physical paths and network bindings before deploying your applications.
**Important considerations for creating different IIS websites**
*Website setup order:* Websites are configured sequentially in the order they appear in the `websites` array. The platform processes each website configuration in sequence, so ensure proper ordering if you have dependencies between websites.
*Firewall and port access:* Only port 80 is automatically exposed through the default Elastic Beanstalk Windows firewall configuration. If you configure websites to use non-standard ports, you must define custom firewall rules through ebextensions or custom deployment scripts to allow external access to these ports.
**Example Website configuration**
```
{
"iisConfig": {
"websites": [
{
"name": "MyCustomSite",
"physicalPath": "C:\inetpub\wwwroot\mysite",
"bindings": [
{
"protocol": "http",
"port": 8080,
"hostName": "mysite.local"
},
{
"protocol": "https",
"port": 8443
}
]
}
]
}
}
```Website properties
`name` (required)
*Type:* String
The name of the IIS website. This name is used to identify the website in IIS Manager and must be unique within the IIS configuration.
`physicalPath` (required)
*Type:* String
The physical path on the server where the website files are stored. This path must be accessible to the IIS worker process.
`bindings` (required)
*Type:* Array
*Minimum items:* 1
An array of binding configurations that define how the website responds to network requests. Each binding specifies a protocol, port, and optional host name.
#### Website bindings
Website bindings define the network endpoints where your IIS website will listen for incoming requests.
`protocol` (required)
*Type:* String
*Valid values:* "http", "https"
The protocol used for the binding.
`port` (required)
*Type:* Integer
*Valid range:* 1-65535
The port number on which the website will listen for requests.
`hostName` (optional)
*Type:* String
The host name (domain name) for the binding.
### Application pools
Application pools provide isolation between applications and allow you to configure runtime settings for groups of applications.
**Example Application pool configuration**
```
{
"iisConfig": {
"appPools": [
{
"name": "MyAppPool",
"enable32Bit": false,
"managedPipelineMode": "Integrated",
"managedRuntimeVersion": "v4.0",
"queueLength": 1000,
"cpu": {
"limitPercentage": 80,
"limitAction": "Throttle",
"limitMonitoringInterval": 5
},
"recycling": {
"regularTimeInterval": 1440,
"requestLimit": 10000,
"memory": 1048576,
"privateMemory": 524288
}
}
]
}
}
```Application pool properties
`name` (required)
*Type:* String
The name of the application pool. This name is used to reference the pool in deployment configurations.
`enable32Bit` (optional)
*Type:* Boolean
Enables a 32-bit application to run on a 64-bit version of Windows. Set to `true` for legacy applications that require 32-bit compatibility.
`managedPipelineMode` (optional)
*Type:* String
*Valid values:* "Integrated", "Classic"
Specifies the request-processing mode for the application pool.
`managedRuntimeVersion` (optional)
*Type:* String
*Valid values:* "No Managed Code", "v2.0", "v4.0"
Specifies the .NET Framework version for the application pool.
`queueLength` (optional)
*Type:* Integer
Maximum number of requests that HTTP.sys queues for the application pool before rejecting additional requests.
#### CPU configuration
The `cpu` object configures CPU usage limits and monitoring for the application pool.
`limitPercentage` (optional)
*Type:* Number
Maximum percentage of CPU time that worker processes in the application pool can consume.
`limitAction` (optional)
*Type:* String
*Valid values:* "NoAction", "KillW3wp", "Throttle", "ThrottleUnderLoad"
Action to take when the CPU limit is reached.
`limitMonitoringInterval` (optional)
*Type:* Number
Reset period (in minutes) for CPU monitoring and throttling limits.
#### Recycling configuration
The `recycling` object configures when and how application pool worker processes are recycled.
`regularTimeInterval` (optional)
*Type:* Integer
Time interval (in minutes) after which the application pool recycles. Set to 0 to disable time-based recycling.
`requestLimit` (optional)
*Type:* Integer
Maximum number of requests the application pool processes before recycling.
`memory` (optional)
*Type:* Integer
Amount of virtual memory (in kilobytes) that triggers worker process recycling.
`privateMemory` (optional)
*Type:* Integer
Amount of private memory (in kilobytes) that triggers worker process recycling.
## Deployment types
The `deployments` object contains arrays of deployment configurations for different application types. Each deployment type has specific properties and use cases.
### MSDeploy deployments
MSDeploy deployments are used for traditional .NET Framework applications that can be deployed using Web Deploy (MSDeploy).
**Example MSDeploy deployment configuration**
```
{
"deployments": {
"msDeploy": [
{
"name": "WebApp",
"description": "Main web application",
"parameters": {
"appBundle": "webapp.zip",
"iisPath": "/",
"appPool": "DefaultAppPool"
}
}
]
}
}
```MSDeploy deployment properties
`name` (required)
*Type:* String
Unique name for the deployment. This name must be unique across all deployments in the manifest.
`description` (optional)
*Type:* String
Human-readable description of the deployment.
`parameters` (required)
*Type:* Object
Configuration parameters for the MSDeploy operation.
`scripts` (optional)
*Type:* Object
PowerShell scripts to run at various stages of the deployment lifecycle.
#### MSDeploy parameters
`appBundle` (required)
*Type:* String
Path to the application bundle (ZIP file) relative to the manifest file. This bundle contains the application files to deploy.
`iisWebSite` (optional)
*Type:* String
*Default:* "Default Web Site"
The IIS website to deploy the application to. By default, applications are deployed to the "Default Web Site". Optionally, you can specify a different website name, such as one configured in the `iisConfig.websites` section.
`iisPath` (optional)
*Type:* String
*Default:* "/"
Virtual directory path in IIS where the application will be deployed. Use "/" for the root path or "/api" for a subdirectory.
`appPool` (optional)
*Type:* String
Name of the application pool to run this application.
### ASP.NET Core deployments
ASP.NET Core deployments are specifically designed for .NET Core and .NET 5\$1 applications.
**Example ASP.NET Core deployment configuration**
```
{
"deployments": {
"aspNetCoreWeb": [
{
"name": "CoreAPI",
"description": "ASP.NET Core Web API",
"parameters": {
"appBundle": "coreapi.zip",
"iisPath": "/api",
"appPool": "CoreAppPool"
}
}
]
}
}
```
ASP.NET Core deployments use the same property structure as MSDeploy deployments, with the key difference being the runtime environment and hosting model used for the application.ASP.NET Core deployment parameters
`appBundle` (required)
*Type:* String
Path to the application bundle relative to the manifest file. This can be either a ZIP archive or a directory path containing the published ASP.NET Core application.
`iisWebSite` (optional)
*Type:* String
*Default:* "Default Web Site"
The IIS website to deploy the ASP.NET Core application to. By default, applications are deployed to the "Default Web Site". Optionally, you can specify a different website name, such as one configured in the `iisConfig.websites` section.
`iisPath` (optional)
*Type:* String
*Default:* "/"
Virtual directory path in IIS for the ASP.NET Core application.
`appPool` (optional)
*Type:* String
Application pool for the ASP.NET Core application. The pool will be configured appropriately for ASP.NET Core hosting.
### Custom deployments
Custom deployments provide complete control over the deployment process through PowerShell scripts. This deployment type is useful for complex scenarios that require custom installation, configuration, or deployment logic.
**Example Custom deployment configuration**
```
{
"deployments": {
"custom": [
{
"name": "CustomService",
"description": "Custom Windows service deployment",
"architecture": 32,
"scripts": {
"install": {
"file": "install-service.ps1"
},
"restart": {
"file": "restart-service.ps1"
},
"uninstall": {
"file": "uninstall-service.ps1",
"ignoreErrors": true
}
}
}
]
}
}
```Custom deployment properties
`name` (required)
*Type:* String
Unique name for the custom deployment.
`description` (optional)
*Type:* String
Description of the custom deployment.
`architecture` (optional)
*Type:* Integer
*Default:* 32
*Valid values:* 32, 64
The architecture specification for execution mode of powershell scripts
`scripts` (required)
*Type:* Object
PowerShell scripts that define the deployment behavior. Custom deployments support additional script types compared to other deployment types.
## Deployment scripts
Deployment scripts are PowerShell scripts that run at specific points during the deployment lifecycle. Different deployment types support different sets of script events.
### Script events
The following script events are available depending on the deployment type:Standard deployment scripts (msDeploy and aspNetCoreWeb)
`preInstall`
Runs before the application is installed or updated.
`postInstall`
Runs after the application is installed or updated.
`preRestart`
Runs before the application is restarted.
`postRestart`
Runs after the application is restarted.
`preUninstall`
Runs before the application is uninstalled.
`postUninstall`
Runs after the application is uninstalled.Custom deployment scripts (custom deployments only)
`install`
Primary installation script for custom deployments. This script is responsible for installing the application or service.
`restart`
Script to restart the application or service. Called when the environment is restarted.
`uninstall`
Script to uninstall the application or service. Called during environment termination or application removal.
### Script properties
Each script is defined as an object with the following properties:
`file` (required)
*Type:* String
Path to the PowerShell script file relative to the manifest file. The script should have a `.ps1` extension.
`ignoreErrors` (optional)
*Type:* Boolean
*Default:* false
When set to `true`, deployment continues even if the script fails. Use this for non-critical scripts or cleanup operations.
**Example Script configuration example**
```
{
"scripts": {
"preInstall": {
"file": "backup-config.ps1",
"ignoreErrors": true
},
"postInstall": {
"file": "configure-app.ps1"
}
}
}
```
# Using EC2 Fast Launch with Windows platform branches
The EC2 Fast Launch feature reduces Windows instance launch times in your Elastic Beanstalk environments. The purpose of this topic is to guide you on using this feature with your Elastic Beanstalk environments. Starting with Windows platform version 2.16.2, released on [January 22, 2025](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2025-01-22-windows.html), Elastic Beanstalk platform releases include base AMIs with EC2 Fast Launch enabled.
## Default EC2 Fast Launch availability
The latest Elastic Beanstalk Windows platform versions include base AMIs with EC2 Fast Launch automatically enabled, with no additional costs. However, when newer platform versions are released, EC2 Fast Launch may not remain automatically enabled on base AMIs from older platform versions.
We recommend upgrading to the latest Windows platform version to use base AMIs with EC2 Fast Launch automatically enabled. However, if you need to continue using your existing platform version, you can manually enable EC2 Fast Launch on your environment's base AMI. For instructions, see [Manually configuring EC2 Fast Launch](#dotnet-ec2fastlaunch-manual).
## Manually configuring EC2 Fast Launch
**Note**
Manually enabling EC2 Fast Launch may incur additional costs compared to using platform versions with EC2 Fast Launch automatically enabled. For more information about EC2 Fast Launch costs, see the [Manage costs for EC2 Fast Launch underlying resources](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/win-fast-launch-manage-costs.html) page in the *Amazon EC2 User Guide*.
Follow these steps to enable EC2 Fast Launch on a Windows base AMI used by your Elastic Beanstalk environment:
**To manually enable EC2 Fast Launch for your Elastic Beanstalk environment**
1. Identify your environment's base AMI:
Follow the steps in [Creating a Custom AMI](using-features.customenv.md) to identify your environment's base AMI ID. Note that you don't need to create a custom AMI - you only need to follow the steps to locate your current base AMI ID.
1. Enable EC2 Fast Launch on the AMI:
Use the instructions in [Enable EC2 Fast Launch](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/win-fast-launch-configure.html) in the *Amazon EC2 User Guide* to configure EC2 Fast Launch for your AMI.