LATEST VERSION: 1.10 - CHANGELOG
Pivotal Cloud Foundry v1.10

Deploying .NET Apps to Windows Cells

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

Overview

After operators have installed and configured the Pivotal Cloud Foundry (PCF) Runtime for Windows v1.10 tile, developers can push .NET apps to the Windows cell. For documentation on 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 (CLI) in order to perform the forthcoming cf push commands. For information on installing the Cloud Foundry CLI, see the Installing the cf CLI topic.

If you have upgraded to PCF Runtime for Windows 1.10 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), which 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. Target the Cloud Controller of your PCF deployment:

    $ cf api api.YOUR-SYSTEM-DOMAIN
    

  2. Push your .NET app, replacing APP-NAME with the name of your app, choose one of the following depending on the app you’re pushing:

    • If you are pushing .NET Framework applications, use the following command:
      $ cf push APP-NAME -s windows2012R2 -b hwc_buildpack
      
    • If you are pushing an application with .bat or .exe files, use the following command:
      $ cf push -s windows2012R2 -b binary_buildpack

    By passing windows2012R2 with the -s flag, you instruct PCF to run the app in the Windows cell. If you are not pushing your app from its directory, add the -p flag to specify the path to the directory that contains the app.

  3. Wait for your app to stage and start. If an error occurs, see the Troubleshoot App Errors section.

Push a Self-Hosted App

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

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

  1. Target the Cloud Controller of your PCF deployment:

    $ cf api api.YOUR-SYSTEM-DOMAIN
    

  2. Push your .NET app from the app root, replacing 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 an error occurs, see the Troubleshoot App Errors section.

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. Push your service from the directory containing the published web service, replacing 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, add the -p flag to your cf push command and specify the path to the directory that contains the published web service.
    • If you do not have a route serving /, add the -u none flag to disable the health check.

  4. If the push command is successful, locate the portion of the 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.

See 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 will route the request 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:

  1. Modify the WSDL file by following the instructions in Modify a Web Service’s WSDL Using a SoapExtensionReflector from the Microsoft Developers Network.

  2. Instruct the developers of external applications that consume the web service to perform the steps in the section below.

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 above.

  4. In Microsoft Visual Studio, right-click on your application in the Solution Explorer and select Add and then 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. Operators should see the Troubleshooting Windows Cells topic for information about how to troubleshoot their 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 specifying 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