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 Pivotal Application Service for Windows (PASW).

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). Using the HWC buildpack requires deploying Windows cells with PASW.

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

  • 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

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

Configure HWC

HWC relies on a Web.config configuration file for configuring the .NET applications.

Most Web.config files work out of the box with PASW, with the following constraints:

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

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

Add a Global Error Handler

Before you push your app for the first time, add a global error handler. Without a global error handler, you will not receive any 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.

Push an App

Follow the steps below to push your application.

  1. Build your app in Visual Studio. On the command line, navigate to the directory that contains the app files.

  2. Run cf push APP-NAME -s windows2016 -b hwc_buildpack to push your app, where APP-NAME is the name you want to give your app. For example:

    $ cf push my-app -s windows2016 -b hwc_buildpack
    Creating app my-app in org sample-org / space sample-space as username@example.com...
    requested state: started
    instances: 1/1
    usage: 1GB x 1 instances
    urls: my-app.example.com
  3. Find the URL of your app in the output from the push command and navigate to it to see your HWC app running. In the example above, my-app.example.com is the URL of your app.


Below are a set of features that can be used with HWC buildpack.

Context Path Routing

Context path routing is a feature analogous to IIS virtual directories. It enables multiple applications to share the same route hostname.

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.

Run the following commands to define context path routing that makes app2 accessible under app1’s URL. For example, app1.example.com/app2:

$ cf push app1 #find the URL for your app1
$ cf push app2 --no-start --no-route
$ cf map-route app2 example.com --hostname app1 --path app2
$ cf start app2

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 features is turned off and unnecessary for apps running under Cloud Foundry. An app can override this setting in its Web.config file.

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 Deploy an Application.

Buildpack Support

A number of channels exist where you can get more help when using the HWC buildpack, or when developing your own HWC buildpack.

Create a pull request or raise an issue on the source for this page in GitHub