Developing and pushing .NET Framework Apps

You can 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 the Steeltoe documentation.

Prerequisites

You have installed and configured 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]. 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 self-hosted or served by Hostable Web Core.
You have installed the Cloud Foundry Command Line Interface (cf CLI). For information about installing the cf CLI, see Installing the cf CLI.

Note 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 capability.

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 these 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.
  
  The -s windows command 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 command 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 host name. 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.

To make 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.
Important The -d parameter is needed only when you push an app to a non-default domain. You can use the routes property in the manifest instead.

Activating a graceful shutdown for a .NET app

Developers can configure .NET apps to shut down gracefully after running the cf stop command. When you run the cf stop command, the .NET app receives a CTRL_SHUTDOWN_EVENT response and is allowed ten seconds to shut down. To activate 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 file.
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 using the procedures in the following sections.

Step 1: Deploy 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 shell and go 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
```
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. The -p parameter is needed only when you push your service from a directory that does not contain the published web service. The -u parameter is needed only when you deactivate the health check when you do not have a route serving /.
Confirm your service is running by finding your service URL in the push command output and browsing to it. In the previous example, the URL for the service is http://webservice.example.com.

Step 2: Edit the WSDL file

Your SOAP web service is now deployed on Operations Manager, but the service WSDL file contains incorrect port information. The WSDL file must be edited to allow an app to consume your web service. Either you or the service developer can perform the needed modification, as shown in this example:

- <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 Garden container, see Container Mechanics in Container Security.

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 default is 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 two ways:

Edit the WSDL file by following the instructions in the Microsoft documentation 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, go 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 Edit the WSDL file.
In Microsoft Visual Studio, right-click your app in the Solution Explorer and select Add > Service Reference.
In 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

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 does not start, review this list of errors and 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 configured wrong or lacks the required DLL files and dependencies. Verify that:
- Your app directory contains either a valid .exe binary or a valid Web.config file.
- You are pushing from a directory containing your app dependencies. If it does not, specify the app dependency directory with the -p flag.