Deploying .NET Apps to Windows Cells

This topic describes how to push .NET apps to Windows cells.

Overview

After operators install and configure the Pivotal Cloud Foundry (PCF) Runtime for Windows v1.11 tile, developers can push .NET apps to the Windows cell. For documentation about installing the PCF Runtime for Windows tile, see the Deploying PCF Runtime for Windows topic. Developers can push both OWIN and non-OWIN apps, and can push apps that are served by Hostable Web Core or self-hosted.

Operators must also install the Cloud Foundry Command Line Interface (cf CLI) to run the commands on this topic. For information about installing the cf CLI, see the Installing the cf CLI topic.

If you have upgraded to PCF Runtime for Windows 1.11 and have apps that you want to migrate, see the Upgrading Windows Cells topic.

Push a .NET App

By default, PCF serves .NET apps with Hostable Web Core (HWC). HWC is a lighter version of the Internet Information Services (IIS) server that contains the core IIS functionality.

Perform the following steps to push a .NET app to a Windows cell:

  1. Run cf api api.YOUR-SYSTEM-DOMAIN to target the Cloud Controller of your PCF deployment:

    $ cf api api.YOUR-SYSTEM-DOMAIN
    

  2. Run one of the following commands to deploy your .NET app, replacing APP-NAME with the name of your app.

    • If you want to deploy a .NET Framework app, run cf push APP-NAME -s windows2012R2 -b hwc_buildpack:
      $ cf push APP-NAME -s windows2012R2 -b hwc_buildpack
      
    • If you want to deploy an app with .bat or .exe files, run cf push -s windows2012R2 -b binary_buildpack:
      $ cf push -s windows2012R2 -b binary_buildpack

      The -s windows2012R2 option instructs PCF to run the app in the Windows cell. If you are not pushing your app from its directory, use the -p option and specify the path to the directory that contains the app.
  3. Wait for your app to stage and start. If you see an error message, refer to the Troubleshoot App Errors section of this topic.

Push a Self-Hosted App

Developers can choose to push a self-hosted app instead of using Hostable Web Core. Self-hosted apps combine server code with the app code.

Perform the following steps to push a self-hosted app:

  1. Run cf api api.YOUR-SYSTEM-DOMAIN to target the Cloud Controller of your PCF deployment:

    $ cf api api.YOUR-SYSTEM-DOMAIN
    

  2. Run cf push APP-NAME -s windows2012R2 -b binary_buildpack -c PATH-TO-BINARY to push your .NET app from the app root. Replace APP-NAME with the name of your app and PATH-TO-BINARY with the path to your executable.

    $ cf push APP-NAME -s windows2012R2 -b binary_buildpack -c PATH-TO-BINARY
    
  3. Wait for your app to stage and start. If you see an error message, refer to the Troubleshoot App Errors section of this topic.

Push a SOAP Service

Developers can push Simple Object Access Protocol (SOAP) web services to their PCF deployment by following the procedures in the sections below.

Step 1: Deploy Your Web Service

Perform the following steps to deploy a SOAP web service:

  1. Develop the service as an ASMX web service in Microsoft Visual Studio.
  2. Publish the service to your local file system.
  3. Run cf push SERVICE-NAME -s windows2012R2 -b hwc_buildpack -u none to push your service from the directory containing the published web service. Replace SERVICE-NAME with the name of your service:

    $ cf push SERVICE-NAME -s windows2012R2 -b hwc_buildpack -u none
    

    The push command must include the -s flag to specify the stack as windows2012R2, which instructs PCF to run the app in the Windows cell.

    The push command can include the following optional flags:

    • If you are not pushing your service from the directory containing the published web service, use the -p flag to specify the path to the directory that contains the published web service.
    • If you do not have a route serving /, use the -u none flag to disable the health check.
  4. Locate the section of the terminal output that displays the URL of the web service:

    requested state: started
    instances: 1/1
    usage: 1G x 1 instances
    urls: YOUR-WEB-SERVICE.YOUR-DOMAIN
    last uploaded: Thu Nov 17 19:18:19 UTC 2016
    stack: windows2012R2
    buildpack: hwc_buildpack
    

Step 2: Modify the WSDL File

Your SOAP web service is now deployed on PCF, but the service’s WSDL file contains the incorrect port information. Before an application can consume your web service, either you or the application developer must modify the WSDL file.

Examine the following portion of an example WSDL file:

- <wsdl:service name="WebService1">
  - <wsdl:port name="WebService1Soap" binding="tns:WebService1Soap">
      <soap:address location="http://webservice.example.com:62492/WebService1.asmx"/>
    </wsdl:port>
  - <wsdl:port name="WebService1Soap12" binding="tns:WebService1Soap12">
      <soap12:address location="http://webservice.example.com:62492/WebService1.asmx"/>
    </wsdl:port>
- </wsdl:service>

The WSDL file provides the port number for the SOAP web service as 62492. This is the port that the web service listens on in the Garden container, but external applications cannot access the service on this port. Instead, external applications must use port 80, and the Gorouter routes requests to the web service in the container.

The URL of the web service in the WSDL file must be modified to remove 62492. With no port number, the URL defaults to port 80. In the example above, the modified URL would be http://webservice.example.com/WebService1.asmx.

SOAP web service developers can resolve this problem in one of two ways:

Consume the SOAP Web Service

Developers of external applications that consume the SOAP web service can perform the following steps to use a modified version of the WSDL file:

  1. In a browser, navigate to the WSDL file of the web service.

    You can reach the WSDL of your web service by constructing the URL as follows: YOUR-WEB-SERVICE.YOUR-DOMAIN/ASMX-FILE.asmx?wsdl

    See the following URL as an example: https://webservice.example.com/WebService1.asmx?wsdl

  2. Download the WSDL file to your local machine.

  3. Edit the WSDL file to eliminate the container port, as described in the Modify the WSDL File section of this topic.

  4. In Microsoft Visual Studio, right-click on your application in the Solution Explorer and select Add > Service Reference.

  5. Under Address, enter the local path to the modified WSDL file. For example, C:\Users\example\wsdl.xml.

  6. Click OK. Microsoft Visual Studio generates a client from the WSDL file that you can use in your codebase.

Troubleshoot App Errors

If a .NET app fails to start, consult the following list of errors and their possible solutions:

  • NoCompatibleCell: Your PCF deployment cannot connect to your Windows cell. See the Troubleshooting Windows Cells topic for information about troubleshooting your Windows cell configuration.

  • Start unsuccessful: Your app may not contain the required DLL files and dependencies. Ensure that you are pushing from a directory containing your app dependencies, or specify the directory with the -p flag. Your app also may be misconfigured. Ensure that your app directory contains either a valid .exe binary or a valid Web.config file.

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