Customizing ASP.NET Core Deployments

In our previous post we announced support for deploying ASP.NET Core applications with AWS Elastic Beanstalk and the AWS Toolkit for Visual Studio. Today, we’ll talk about how deployment works and how you can customize it.

After you go through the deployment wizard in the AWS Toolkit for Visual Studio, the toolkit bundles the application and sends it to Elastic Beanstalk. When the toolkit creates the bundle, the first step is to use the new dotnet CLI and the publish command to prepare the application for publishing. The settings in the wizard pass the framework and configuration to the publish command. So if you selected Release for configuration and netcoreapp1.0 for the framework, the toolkit will execute the following command.

dotnet publish --configuration Release --framework netcoreapp1.0

When the publish command finishes, the toolkit writes the new deployment manifest into the publishing folder. The deployment manifest is a JSON file named aws-windows-deployment-manifest.json, which is read by the new tooling added to the 1.2 version of the Elastic Beanstalk Windows container to figure out how to deploy the application. For example, for an ASP.NET Core application that you want to deploy at the root of IIS, the toolkit generates a manifest file that looks like this.

{
  "manifestVersion": 1,
  "deployments": {
 
    "aspNetCoreWeb": [
      {
        "name": "app",
        "parameters": {
          "appBundle": ".",
          "iisPath": "/",
          "iisWebSite": "Default Web Site"
        }
      }
    ]
  }
}

The appBundle property indicates where the application bits are in relation to the manifest file. This property can point to either a directory or a ZIP archive. The iisPath and iisWebSite properties indicate where in IIS to host the application.

Declaring the Manifest

The toolkit only writes the manifest file if it doesn’t already exist in the publishing folder. If the file does exist, the toolkit updates the appBundle, iisPath, and iisWebSite properties in the first application listed in the aspNetCoreWeb section of the manifest. This allows you to add the aws-windows-deployment-manifest.json to your project and customize the manifest. To do this for an ASP.NET Core Web application in Visual Studio, add a new JSON file to the root of the project and name it aws-windows-deployment-manifest.json.

The manifest must be named aws-windows-deployment-manifest.json and it must be at the root of the project. The Elastic Beanstalk container looks for the manifest at the root and, if it finds it, will invoke the new deployment tooling. If the file doesn’t exist, the Elastic Beanstalk container falls back to the older deployment tooling, which assumes the archive is a msdeploy archive.

To ensure the dotnet CLI publish command includes the manifest, you must update the project.json file to include the manifest file in the include section that’s under publishOptions.

Customizing the Manifest File for Application Deployment

Now that you’ve declared the manifest so that it’s included in the app bundle, you can go beyond what the wizard supports to customize your application’s deployment. AWS has defined a JSON schema for aws-windows-deployment-manifest.json. When you installed the AWS Toolkit for Visual Studio, the setup registers deployment manifest schema.

If you look at the Schema box, you’ll see the schema is set to aws-windows-deployment-manifest-schema.json. When the schema is selected, Visual Studio provides IntelliSense while you’re editing the manifest.

For non Visual Studio users the deployment manifest schema can be accessed online here.

One customization you can do is to configure the IIS application pool that runs the application. The following example shows how you can define an IIS application pool that recycles the process every hour and assigns it to the application.

Additionally, the manifest can declare Windows PowerShell scripts to run before and after the install, restart, and uninstall actions. For example, the following manifest runs the Windows PowerShell script PostInstallSetup.ps1 to do more setup work after the ASP.NET Core application is deployed to IIS. Remember, just like the aws-windows-deployment-manifest.json file, be sure to add your scripts to the include section under publishOptions in the project.json file. If you don’t, the scripts won’t be included in the dotnet CLI publish command.

{
  "manifestVersion": 1,
  "deployments": {
    "aspNetCoreWeb": [
      {
        "name": "app",
        "scripts": {
          "postInstall": {
            "file": "SetupScripts/PostInstallSetup.ps1"
          }  
        }  
      }   
    ]
  }
}

What about ebextensions?

The Elastic Beanstalk ebextensions configuration files are still supported like all the other Elastic Beanstalk containers. To include them in an ASP.NET Core application, add the .ebextensions directory to the include section under publishOptions in the project.json file. For more information about ebextensions, check out the Elastic Beanstalk Developer Guide.

We hope this post gives you a better understanding of how deploying ASP.NET Core applications to Elastic Beanstalk works. In our next post, we’ll show you how to use the new deployment manifest file to deploy multiple applications to the same Elastic Beanstalk environment.