Skip to main content

Install the .NET Framework agent using a container

Before you begin

This topic provides general guidance for installing the Contrast .NET Framework agent in a containerized application, with Docker as an example.

You should have a basic understanding of how containers and related software work. You may need to adjust the instructions to meet your specific circumstances.

Step 1: Install the agent

In this example, the latest .NET Framework agent is copied. Check DockerHub for available tags.


# Hidden for brevity...

# Copy the required agent files from the official Contrast agent image.
COPY --from=contrast/agent-dotnet-framework:latest C:\Contrast C:\Contrast

In this example, the latest .NET Framework agent is copied. Check DockerHub for available tags.

Step 2: Configure the agent

Contrast agents accept configuration from multiple sources, with order of precedence documented in the order of precedence section.

A mixed approach is recommended:

  • Use a YAML file so that you can share a common configuration between multiple applications.

  • Use environment variables for application-specific configuration values, to override values specified in a YAML file, or for sensitive keys that are injected during runtime.

YAML file configuration:

When you use a YAML file to configure the agent, you can use the environment variable CONTRAST_CONFIG_PATH to indicate where the YAML file is located inside the container.

For example, given a YAML file called contrast_security.yaml that exists in the Docker build context:

    path: /var/tmp
    level: WARN

You can use the CONTRAST_CONFIG_PATH environment variable to add the agent YAML file to the container image as follows:


# Hidden for brevity...

# Add the Contrast agent to the image.
COPY --from=contrast/agent-dotnet-framework:latest C:\Contrast C:\Contrast

# Copy the contrast_security.yaml file from Docker build context.
COPY ./contrast_security.yaml /contrast_security.yaml

# Finally configure configure the agent to use the YAML file previously copied.
ENV CONTRAST_CONFIG_PATH=/contrast_security.yaml

Environment variable configuration:

To set an application-specific configuration, use environment variables. This table contains some common configuration options.



Environment variable

Application name

Specify the application name reported to Contrast.


Application group

Specify the application access group for this application during onboarding.


Create application access groups in Contrast before using this variable.


Application tags

Add labels to an application.


Server name

Specify the server name reported to Contrast.


Server environment

Specify in which environment the application is running. Valid values for this configuration are: Development, QA, and Production.


Server tag

Add labels to the server.


Step 3: Add profiler variables and authentication credentials

To enable instrumentation of your application, the .NET agent requires additional environment variables. The COR_CLR variables load the agent and the CONTRAST_ variables are for agent authentication to the server.

Using the Dockerfile example in this topic:


COPY --from=contrast/agent-dotnet-framework:latest C:\Contrast C:\Contrast

    COR_PROFILER={EFEB8EE0-6D39-4347-A5FE-4D0C88BC5BC1} \
    COR_PROFILER_PATH_32=C:\Contrast\runtimes\win-x86\native\ContrastProfiler.dll \

Additionally, the following environment variables are required for agent authentication to the server.

CONTRAST__API__SERVICE_KEY={Your Service key here}

Get the API values (agent keys) from the Contrast web interface or by downloading a YAML file for the .NET Framework agent.


You can see examples of finished code in this GitHub repository. In particular, these ASP.NET application use cases might be helpful:

See also

Contrast Support Portal Kubernetes and Contrast

Contrast Support Portal AWS Fargate and Contrast agents