# Cloud Foundry Integration

SeaLights .NET agent is integrated into the Cloud Foundry [.NET core buildpack](https://github.com/cloudfoundry/dotnet-core-buildpack). So you can use it in your application by performing the following simple steps:

1. Create SeaLights service configuration
2. Push an application
3. Bind an application with the service
4. Restage an application

### Create Service Configuration <a href="#create-service-configuration" id="create-service-configuration"></a>

To manage application integrations with third-party services Cloud Foundry has the mechanism of the [User-Provided Services](https://docs.cloudfoundry.org/devguide/services/user-provided.html). So the first step is to create such a service with the configuration. Here is the command “[create-user-provided-service](https://cli.cloudfoundry.org/en-US/v7/create-user-provided-service.html)“ that does that:

{% code overflow="wrap" lineNumbers="true" %}

```sh
cf cups sealights-dotnet -p '{"token":"ey…", "buildSessionId":"as…"}'
```

{% endcode %}

Note: you have to escape the `"` character in the windows commands line, so the command will look like this:

{% code overflow="wrap" lineNumbers="true" %}

```
cf cups sealights-dotnet -p '{\"token\":\"ey…\", \"buildSessionId\":\"as…\"}'
```

{% endcode %}

You will be able to change the parameters later with the command “[update-user-provided-service](https://cli.cloudfoundry.org/en-US/v7/update-user-provided-service.html)”

See below the complete list of the available parameters

{% hint style="info" %}
Important is only a prefix of the service name. It means that the service “sealights-build001” will also enable sealights integration. This can be useful when you create ups in pipeline - you can pass the build number to the service name, do bind, and then unbind it in a clean-up build stage
{% endhint %}

### Push an application <a href="#push-an-application" id="push-an-application"></a>

You can push an application as usual with the command “[push](https://cli.cloudfoundry.org/en-US/v7/push.html)” just taking into account that to perform the `testListener` phase in the CloudFoundry container you have to publish an application unit test

{% code overflow="wrap" lineNumbers="true" %}

```
cf push
```

{% endcode %}

Note: You can use a [manifest.yml](https://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html) file to simplify an application deployment

### Bind Application with the service <a href="#bind-application-with-the-service" id="bind-application-with-the-service"></a>

Now you can bind your published application with the service

{% code overflow="wrap" lineNumbers="true" %}

```
cf bind-service [app name] sealights-dotnet
```

{% endcode %}

### Restage Application <a href="#restage-application" id="restage-application"></a>

In order to apply changes you have to publish your application again, or just restage it with a command [restage](https://cli.cloudfoundry.org/en-US/v7/restage.html)

{% code overflow="wrap" lineNumbers="true" %}

```
cf restage [app name]
```

{% endcode %}

### Sealights user-provided service options <a href="#sealights-user-provided-service-options" id="sealights-user-provided-service-options"></a>

<table><thead><tr><th width="184.66668701171875">Prameter name</th><th>Description</th></tr></thead><tbody><tr><td><code>verb</code> <br><mark style="color:red;"><strong>(Required)</strong></mark></td><td>The verb that will be passed to the sealights agent. If not provided - an application will be started without modifications of the start command - that means without sealights agent.</td></tr><tr><td><code>version</code></td><td>By default pointer to the latest released version. Use this parameter if you want to use some specific agent version</td></tr><tr><td><code>customAgentUrl</code></td><td>This URL can be used to replace agent installation package completely with another one. Expect url to tar.gz archive</td></tr><tr><td><code>labId</code></td><td>Allow to determine customer lab id - unique ID for a set of test labs in case multiple labs are running simultaneously</td></tr><tr><td><code>proxy</code></td><td>Address of proxy that will be used to download an agent</td></tr><tr><td><code>proxyUsername</code></td><td>The proxy username if needed</td></tr><tr><td><code>proxyPassword</code></td><td>The proxy password if needed</td></tr><tr><td><code>parseArgsFromCmd</code></td><td>If <code>true</code> parameters <code>workingDir</code> <code>target</code> <code>targetArgs</code> will be parsed from the application launch command</td></tr><tr><td><code>customCommand</code> <mark style="background-color:$info;">DEV</mark></td><td>Allows to replace application launch command</td></tr></tbody></table>

{% hint style="info" %}
All other parameters will be passed to the Agent as is. This allows to support all future changes of the agent without the buildpack modifications
{% endhint %}

### How does it work <a href="#how-does-it-work" id="how-does-it-work"></a>

Sealights use the AfterCompile hook in the `dotnet-core-buildpack` to install an agent and all required dependencies in the target container. So once the application is pushed to the cloud foundry service the following steps occur:

1. Sealights hook verifies that the application is bound with the sealights service
2. If so, hook download a package with an agent
3. Install the agent from the package
4. Install dotnet runtime specific used by the agent
5. Modify target application start command

{% code overflow="wrap" lineNumbers="true" %}

```
[cd to the working directory] && dotnet SL.DotNet.dll [verb] [options]
```

{% endcode %}

In case when verb is `startBackgroundTestListener` and `testListenerSessionKey` is provided buildpack integration will create an additional file - `sealights.envrc` with all environment variables required for the profiler to attach to the target application.\
The start command will look like this:

{% code overflow="wrap" lineNumbers="true" %}

```
[cd to the working directory] 
&& dotnet SL.DotNet.dll [verb] [options] 
&& source sealights.envrc 
&& [start target application]
```

{% endcode %}

6. Once the service is ready you can execute additional commands via cf run-task API