Tips for .NET Framework Developers

Warning: Pivotal Cloud Foundry (PCF) v2.3 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.

This topic describes how to push .NET Framework apps to Pivotal Application Service (PAS) for Windows cells.

For how to develop microservices for .NET Framework and .NET Core using Steeltoe, see the Steeltoe documentation.

Prerequisites

The PAS for Windows tile must be installed and configured. For documentation about installing the PAS for Windows tile, see the Installing and Configuring PAS for Windows topic.

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.

Overview

After operators install and configure the PAS for Windows tile, developers can push .NET Framework apps to the Windows cell. Developers can push both OWIN and non-OWIN apps, and can push apps that are served by Hostable Web Core or self-hosted.

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

Develop .NET Framework Apps

.NET on PCF Cookbook

The .NET Cookbook has useful tips and recipes for migrating and developing .NET Framework apps to run on PAS for Windows.

Push a .NET Framework App

By default, PCF serves .NET Framework 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 Framework app to a Windows cell:

  1. To target the Cloud Controller of your PCF deployment, run the following command:

    cf api api.APP-DOMAIN
    

    Where APP-DOMAIN is your application’s public domain name, for example: example.com.

  2. Run one of the following commands to deploy your .NET app:

    • To deploy an app with .bat or .exe files, run the following command:
    cf push -s windows -b binary_buildpack
    
    • To deploy a .NET Framework app, run the following command:
    cf push APP-NAME -s windows -b hwc_buildpack  
    

    Where APP-NAME is the name of your application.

    Note: The -s windows option instructs PCF to run the app in the Windows cell.

    Note: 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, see the Troubleshoot App Errors section of this topic.

Context Path Routing Support for ASP.NET Apps

Context path routing enables multiple apps to share the same route hostname, such as app1.example.com/app2. ASP.NET developers can host apps under a route path. Within Windows cells, you can have multiple routes to an app, but those routes cannot have different context paths.

Making an app accessible under another app’s URL requires a pair of commands. To define a context path route, such as app1.example.com/app2, run the following commands:

  1. To push the top-level app, run the following command:

    cf push TOP-LEVEL-APP-NAME
    

    Where TOP-LEVEL-APP-NAME is the name of your top-level app.

  2. To push the lower-level app, run the following command:

    cf push LOWER-LEVEL-APP-NAME -d APP-DOMAIN --hostname TOP-LEVEL-APP-NAME --route-path LOWER-LEVEL-APP-NAME
    

    Where:

    • TOP-LEVEL-APP-NAME is the name of your top-level app.
    • LOWER-LEVEL-APP-NAME is the name of your lower-level app.
    • APP-DOMAIN is your application’s public domain name, for example: example.com.

    Note: The -d parameter is only needed when pushing an app to a non-default domain.

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. To target the Cloud Controller of your PCF deployment, run the following command:

    cf api api.APP-DOMAIN
    

    Where APP-DOMAIN is your application’s public domain name, for example: example.com.

  2. To push your .NET app from the app root, run the following command:

    cf push APP-NAME -s windows -b binary_buildpack -c PATH-TO-BINARY
    

    Where:

    • APP-NAME is the name of your app.
    • PATH-TO-BINARY is the path to your executable.
  3. Wait for your app to stage and start. If you see an error message, see 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. Open a command line to the directory containing the published web service.
  4. To push your service, run the following command:

    cf push SOAP-SERVICE-NAME -s windows -b hwc_buildpack -p WEB-SERVICE-DIRECTORY -u none
    

    Where

    • SOAP-SERVICE-NAME is the name of your service.
    • WEB-SERVICE-DIRECTORY is the path to the directory containing the published web service.

    For example:

    $ cf push webservice -s windows -b hwc_buildpack -u none
    
    requested state: started
    instances: 1/1
    usage: 1G x 1 instances
    urls: webservice.example.com
    

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

    Note: The -p and -u parameters are optional parameters. The -p parameter is needed only when pushing your service from a directory that does not contain the published web service. The -u parameter is needed only when disabling the health check when you do not have a route serving /.

  5. Confirm your service is running by finding your service’s URL in the push command’s output and browsing to it. In the example above, the URL for the service would be: http://webservice.example.com.

Step 2: Modify the WSDL File

Your SOAP web service is now deployed on PCF, but the service’s WSDL file contains incorrect port information. The WSDL file must be modified to enable an app to consume your web service. Either you or the service developer can perform the needed modification.

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, using the following URL:

    https://SOAP-SERVICE-NAME.APP-DOMAIN/ASMX-FILE?wsdl
    

    Where:

    • SOAP-SERVICE-NAME is the name of your service.
    • APP-DOMAIN is your site’s public domain name.
    • ASMX-FILE is the filename of your asmx file.

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

Context Path Routing Support for SOAP Web Services

Developers can push SOAP web services to their PCF deployment with context path routing. For more information, see the Context Path Routing Support for ASP.NET Apps section.

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. For information about troubleshooting your Windows cell configuration, see the Troubleshooting Windows Cells topic.

  • Start unsuccessful: Your app may may be misconfigured or lacks the required DLL files and dependencies.

    • Ensure that your app directory contains either a valid .exe binary or a valid Web.config file.
    • Ensure that you are pushing from a directory containing your app dependencies. If it does not, specify the app dependency directory with the -p flag.