Developing and pushing .NET Framework Apps

This topic tells you how to push .NET Framework apps to VMware Tanzu Application Service for VMs [Windows] Diego Cells.

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

Prerequisites

The TAS for VMs [Windows] tile must be installed and configured. To install TAS for VMs [Windows], see Installing and configuring TAS for VMs [Windows].

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 Installing the cf CLI.

After you install and configure the TAS for VMs [Windows] tile, developers can push .NET Framework apps to the Windows Diego 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 upgrade to TAS for VMs [Windows] and have apps that you want to migrate, see Upgrading Windows Diego Cells.

Developing .NET Framework Apps

.NET on Operations Manager cookbook

For useful tips and recipes for migrating and developing .NET Framework apps to run on TAS for VMs [Windows], see the .NET Cookbook.

Pushing a .NET Framework App

By default, Operations Manager 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.

To push a .NET Framework app to a Windows Diego Cell:

Target the Cloud Controller of your Operations Manager deployment by running:
```
cf api api.APP-DOMAIN
```
Where APP-DOMAIN is your app’s public domain name. For example, example.com.
Run one of the following commands to deploy your .NET app:
- To deploy an app with .bat or .exe files, run:
```
cf push -s windows -b binary_buildpack
```
- To deploy a .NET Framework app, run:
```
cf push APP-NAME -s windows -b hwc_buildpack
```
  Where APP-NAME is the name of your app.
  
  Note The -s windows option instructs Operations Manager to run the app in the Windows Diego 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.
Wait for your app to stage and start. If you see an error message, see Troubleshoot App Errors.

Context Path Routing Support for ASP.NET Apps

With context path routing, you can activate multiple apps to share the same route hostname. For example, app1.example.com/app2. If you use ASP.NET you can host apps under a route path. Within Windows Diego 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:

Push the top-level app by running:
```
cf push TOP-LEVEL-APP-NAME
```
Where TOP-LEVEL-APP-NAME is the name of your top-level app.
Push the lower-level app by running:
```
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 app's public domain name. For example, example.com.
Note The -d parameter is only needed when pushing an app to a non-default domain.

Activating a graceful shutdown for a .NET App

Developers can configure .NET apps to shut down gracefully after running cf stop. When you run cf stop, the .NET app receives a CTRL_SHUTDOWN_EVENT and is allowed ten seconds to shut down. To enable graceful shutdown, you must include a control handler in the app.

For more information, see Graceful Shutdown in the .NET Cookbook.

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

To push a self-hosted app:

Target the Cloud Controller of your Operations Manager deployment by running:
```
cf api api.APP-DOMAIN
```
Where APP-DOMAIN is your app’s public domain name. For example, example.com.
Push your .NET app from the app root by running:
```
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.
Wait for your app to stage and start. If you see an error message, see Troubleshoot App Errors.

Push a SOAP Service

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

Step 1: Deploying your Web Service

To deploy a SOAP web service:

Develop the service as an ASMX web service in Microsoft Visual Studio.
Publish the service to your local file system.
Open a command line to the directory containing the published web service.
Push your service by running:
```
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
```
Important The push command must include the -s flag to specify the stack, which instructs Operations Manager to run the app in the Windows Diego Cell. 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 /.
Confirm your service is running by finding your service’s URL in the push command’s output and browsing to it. In the previous example, the URL for the service is http://webservice.example.com.

Step 2: Modifying the WSDL File

Your SOAP web service is deployed on Operations Manager, 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.

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 apps cannot access the service on this port. Instead, external apps must use port 80, and the Gorouter routes requests to the web service in the container.

For more information about the Gorouter, see TAS for VMs routing architecture.

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 previous example, the modified URL is http://webservice.example.com/WebService1.asmx.

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

Modify the WSDL file by following the instructions in Modify a Web Service’s WSDL Using a SoapExtensionReflector from the Microsoft Developers Network.
Instruct the developers of external apps that consume the web service to follow the procedure in Consuming SOAP Web Service.

Consuming SOAP Web Service

Developers of external apps that consume the SOAP web service can use a modified version of the WSDL file.

To use a modified version of the WSDL file:

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
```
Download the WSDL file to your local machine.
Edit the WSDL file to delete the container port, as described in Modify the WSDL File.
In Microsoft Visual Studio, right click your app in the Solution Explorer and select Add > Service Reference.
Under Address, enter the local path to the modified WSDL file. For example:
```
C:\Users\example\wsdl.xml
```
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

Context path routing support for SOAP Web Services

Developers can push SOAP web services to their Operations Manager deployment with context path routing.

For more information, see Context path routing support for ASP.NET Apps.

Troubleshooting App errors

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

NoCompatibleCell: Your Operations Manager deployment cannot connect to your Windows Diego Cell. For more information about troubleshooting your Windows Diego Cell configuration, see Troubleshooting Windows Diego Cells.
Start unsuccessful: Your app might 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.