HWC Buildpack

Page last updated:

This topic describes how to configure your .NET Framework apps for use with the HWC buildpack and how to push your .NET Framework apps to VMware Tanzu Application Service for VMs [Windows].

Prerequisites

Using the HWC buildpack requires deploying Windows cells with TAS for VMs [Windows].

The HWC buildpack supports the following common app types by default:

  • ASP.NET MVC
  • ASP.NET Web Forms
  • ASP.NET WebAPI Apps
  • Windows Communication Foundation (WCF)

For information about deploying different types of .NET apps, follow the links in the table below.

Type of .NET App Buildpack
.NET Console Binary
.NET Core pushed to Linux stack .NET Core
.NET Core pushed to Windows stack Binary

Overview

The HWC buildpack provides a runtime server that uses the Hosted Web Core API for running .NET Framework applications in Windows Server containers. For more information, see Hosted Web Core API Reference in the Microsoft documentation.

The HWC buildpack provides access to .NET Framework 4.5.1 and later, made available by the Windows root file system (rootfs).

Before you push your first app using the HWC buildpack, see the Getting Started guide in the .NET Cookbook.

Step 1. Configure HWC

HWC relies on Web.config and applicationHost.config configuration files for configuring the .NET applications.

Most Web.config files work out of the box with TAS for VMs [Windows], with the following constraints:

  • Integrated Windows Authentication (IWA) is not yet supported on TAS for VMs [Windows].
  • SQL server connection strings must use fully qualified domain names.
  • Place connection string values in environment variables or user-provided service instances.

Additionally, Shadow Copy Setting, and Dynamic and Static HTTP Compression Web.config settings can be customized as needed.

The HWC buildpack includes a default configuration for the applicationHost.config, similar to IIS.

Step 2. Add a Global Error Handler

Before you push your app for the first time, add a global error handler to receive log information from your app if it crashes on startup.

To configure a global error handler that logs to stdout, see Application Error Handling in the .NET Cookbook.

Step 3. Push an App

Follow the steps below to push your application.

  1. Build your HWC app in Visual Studio.

  2. On the command line, navigate to the directory containing the app files.

  3. To push your HWC app, run the following cf push command:

    cf push APP-NAME -s windows -b hwc_buildpack

    Where APP-NAME is the name you want to give your app.
    For example:

    $ cf push my-app -s windows -b hwc_buildpack
Creating app my-app in org sample-org / space sample-space as username@example.com...
OK
...
requested state: started
instances: 1/1
usage: 1 GB x 1 instances
urls: my-app.example.com

  4. Confirm your application is running by finding your app’s URL in the push command output and navigating to it. In the example above, my-app.example.com is the URL of your app.

Features

The following features can be used with HWC buildpack:

Context Path Routing

Context path routing enables multiple apps to share the same route hostname, such as app1.example.com/app2. The context path routing feature is analogous to IIS virtual directories.

Making an application accessible under another app’s URL requires pushing both apps and applying a map-route between them. To define a context path route, such as app1.example.com/app2, run the following commands:

  1. To push the primary app, run the following command:

    cf push TOP-LEVEL-APP-NAME -s windows -b hwc_buildpack

    Where TOP-LEVEL-APP-NAME is your top-level app’s name.

  2. To push the secondary app and disable the app’s starting and default routing, run the following command:

    cf push LOWER-LEVEL-APP-NAME --no-start --no-route -s windows -b hwc_buildpack

    Where LOWER-LEVEL-APP-NAME is your lower-level app’s name.

  3. To map routes between the primary and secondary apps, run the following command:

    cf map-route LOWER-LEVEL-APP-NAME APP-DOMAIN --hostname TOP-LEVEL-APP-NAME --path LOWER-LEVEL-APP-NAME

    Where:

    • TOP-LEVEL-APP-NAME is your top-level app’s name.
    • LOWER-LEVEL-APP-NAME is your lower-level app’s name.
    • APP-DOMAIN is your site’s public domain name.

  4. To start the secondary app, run the following command:

    cf start LOWER-LEVEL-APP-NAME

    Where LOWER-LEVEL-APP-NAME is your lower-level app’s name.

For example, the following commands define context path routing for two HWC apps, app1 and app2, where app2 is made accessible under app1 as app1.example.com/app2:

$ cf push app1 -s windows -b hwc_buildpack
$ cf push app2 --no-start --no-route -s windows -b hwc_buildpack
$ cf map-route app2 example.com --hostname app1 --path app2
$ cf start app2

Note: HWC-hosted apps use the VCAP_APPLICATION environment variable to read out the bound app URIs. Any context path that exists underneath the root in the app’s bound route corresponds to the applicationHost.config.

Shadow Copy Setting

Shadow Copy is a hosting option that copies assemblies for an app in the bin directory to the app’s temporary files directory. This feature is turned off and unnecessary for apps running under Cloud Foundry. An app can override this setting in its Web.config file.

Dynamic and Static HTTP Compression

The HWC buildpack enables dynamic and static HTTP compression by default. You can disable HTTP compression in your app’s Web.config file.

Dynamic HTTP compression is hardcoded at level 4. Static HTTP compression is hardcoded at level 9.

URL Rewrite

The HWC buildpack supports the URL Rewrite module. It is preinstalled in the Windows file system.

Profile Scripts

The HWC buildpack allows developers to provide .profile.bat scripts with their applications. You can use a .profile.bat script to perform app-specific initialization tasks, such as setting custom environment variables.

For information about configuring .profile.bat scripts, see the Configure Pre-Runtime Hooks section of Pushing an App.

Buildpack Support

A number of channels exist to assist you with using the HWC buildpack, or when developing your own HWC buildpack.