forked from dawu415/docs-pcf-windows
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathusing.html.md.erb
233 lines (151 loc) · 11.4 KB
/
using.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
---
title: Tips for .NET Framework Developers
owner: Greenhouse
---
This topic describes how to push .NET Framework apps to <%= vars.windows_runtime_full %> Diego Cells.
For information about how to develop microservices for .NET Framework and .NET Core using Steeltoe, see the [Steeltoe documentation](http://steeltoe.io/docs/).
## <a id='prerequisites'></a> Prerequisites
The <%= vars.windows_runtime_abbr %> tile must be installed and configured. To install <%= vars.windows_runtime_abbr %>, see [Installing and Configuring <%= vars.windows_runtime_abbr %>](installing.html).
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](../cf-cli/install-go-cli.html).
## <a id='overview'></a> Overview
After operators install and configure the <%= vars.windows_runtime_abbr %> tile, developers can push .NET Framework apps to the Windows Diego Cell. Developers can push both [OWIN](http://owin.org/) and non-OWIN apps, and can push apps that are served by Hostable Web Core or self-hosted.
If you have upgraded to <%= vars.windows_runtime_abbr %> and have apps that you want to migrate, see [Upgrading Windows Diego Cells](upgrade-windows.html).
## <a id='develop'></a> Develop .NET Framework Apps
### <a id='cookbook'></a> .NET on <%= vars.platform_name %> Cookbook
For useful tips and recipes for migrating and developing .NET Framework apps to run on <%= vars.windows_runtime_abbr %>, see the [.NET Cookbook](https://dotnet-cookbook.apps.pcfone.io/intro/).
## <a id='push'></a> Push a .NET Framework App
By default, <%= vars.platform_name %> 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:
1. Target the Cloud Controller of your <%= vars.platform_name %> deployment by running:
```
cf api api.APP-DOMAIN
```
Where `APP-DOMAIN` is your app's public domain name. For example, `example.com`.
1. 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:
```shell
cf push APP-NAME -s windows -b hwc_buildpack
```
Where `APP-NAME` is the name of your app.
<p class="note"><strong>Note:</strong> The <code>-s windows</code> option instructs <%= vars.platform_name %> to run the app in the Windows Diego Cell.</p>
<p class="note"><strong>Note:</strong> If you are not pushing your app from its directory, use the <code>-p</code> option and specify the path to the directory that contains the app.</p>
1. Wait for your app to stage and start. If you see an error message,
see [Troubleshoot App Errors](#troubleshoot) below.
### <a id='context-routing'></a> 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 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`:
1. 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.
1. 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`.
<p class="note"><strong>Note:</strong> The <code>-d</code> parameter is only needed when pushing an app to a non-default domain.</p>
### <a id='graceful-shutdown'></a> Enable 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](https://dotnet-cookbook.apps.pcfone.io/aspnet/graceful-shutdown/) in the .NET Cookbook.
## <a id='self-hosted'></a> 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.
To push a self-hosted app:
1. Target the Cloud Controller of your <%= vars.platform_name %> deployment by running:
```
cf api api.APP-DOMAIN
```
Where `APP-DOMAIN` is your app's public domain name. For example, `example.com`.
1. 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.
1. Wait for your app to stage and start. If you see an error message,
see [Troubleshoot App Errors](#troubleshoot) below.
## <a id='soap'></a> Push a SOAP Service
Developers can push Simple Object Access Protocol (SOAP) web services to their <%= vars.platform_name %> deployment by following the procedures in the sections below.
### <a id='push-soap'></a> Step 1: Deploy Your Web Service
To deploy a SOAP web service:
1. Develop the service as an ASMX web service in Microsoft Visual Studio.
1. Publish the service to your local file system.
1. Open a command line to the directory containing the published web service.
1. 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.
<br>
For example:
<pre class='terminal'>
$ cf push webservice -s windows -b hwc_buildpack -u none
<br>
requested state: started
instances: 1/1
usage: 1G x 1 instances
urls: webservice.example.com
</pre>
<p class="note"><strong>Note:</strong> The push command must include the <code>-s</code> flag to specify the stack, which instructs <%= vars.platform_name %> to run the app in the Windows Diego Cell.</p>
<p class="note"><strong>Note:</strong> The <code>-p</code> and <code>-u </code> parameters are optional parameters. The <code>-p</code> parameter is needed only when pushing your service from a directory that does not contain the published web service. The <code>-u</code> parameter is needed only when disabling the health check when you do not have a route serving <code>/</code>.</p>
1. 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`.
### <a id='correct-wsdl'></a> Step 2: Modify the WSDL File
Your SOAP web service is now deployed on <%= vars.platform_name %>, 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:
```xml
- <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](../concepts/container-security.html#mechanics) in _Container Security_. For more information about the Gorouter, see [<%= vars.app_runtime_abbr %> Routing Architecture](../concepts/cf-routing-architecture.html).
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:
* Modify the WSDL file by following the instructions in [Modify a Web Service's WSDL Using a SoapExtensionReflector](https://blogs.msdn.microsoft.com/kaevans/2005/11/16/modify-a-web-services-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 [Consume the SOAP Web Service](#consume).
#### <a id='consume'></a> Consume the 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:
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.
<br>
For example:
```
https://webservice.example.com/WebService1.asmx?wsdl
```
1. Download the WSDL file to your local machine.
1. Edit the WSDL file to eliminate the container port, as described in [Modify the WSDL File](#correct-wsdl).
1. In Microsoft Visual Studio, right-click on your app in the **Solution Explorer** and select **Add** > **Service Reference**.
1. Under **Address**, enter the local path to the modified WSDL file. For example:
```
C:\Users\example\wsdl.xml
```
1. Click **OK**. Microsoft Visual Studio generates a client from the WSDL file that you can use in your codebase.
#### <a id='context-routing-soap'></a> Context Path Routing Support for SOAP Web Services
Developers can push SOAP web services to their <%= vars.platform_name %> deployment with context path routing. For more information, see [Context Path Routing Support for ASP.NET Apps](#context-routing).
## <a id='troubleshoot'></a> Troubleshoot App Errors
If a .NET app fails to start, see the following list of errors and their possible solutions:
* `NoCompatibleCell`: Your <%= vars.platform_name %> deployment cannot connect to your Windows Diego Cell. For more information about troubleshooting your Windows Diego Cell configuration, see [Troubleshooting Windows Diego Cells](troubleshooting.html).
* `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.