Contrast Windows installer

The Contrast .NET Framework agent installer is a normal Windows application installer built using standard MSI technology. It validates that the target server satisfies several requirements (for example, that the server's operating system is a supported operating system). If all requirements are met, the installer:

  • Registers the .NET Framework agent as a standard Windows program.

  • Places the agent’s files on a disk in the specified install location (for example, C:\Program Files\Contrast\dotnet). This includes several dynamic link libraries (DLLs) and executables, such as the background Windows service that drives agent behavior.

  • Creates the specified data directory for the agent that's primarily used to store agent log files and configuration (for example, C:\ProgramData\Contrast\dotnet).

  • Registers the agent’s background Window service with the operating system.

  • Starts the agent’s background Windows service and Contrast tray application. This service is responsible for:

    • Preparing the environment for instrumentation by registering the agent’s profiler component with IIS through environment variables, and restarting IIS. This causes the CLR to load the agent’s profiler, which is responsible for instrumenting analyzed applications.

    • Communication with profiler and sensor components through local named pipes.

Note

To install the .NET Framework agent using Contrast:

  1. In the Contrast web application, select Add agent in the top right.

  2. Choose .NET Framework in the application language drop-down menu, then select IIS hosted and select the link to Download the agent and YAML configuration file.

  3. Extract the downloaded ZIP archive on the web server, and run ContrastSetup.exe. This installs the .NET Framework agent.

    The contrast_security.yaml file is copied to the agent's data directory by the installer and placed in C:\ProgramData\Contrast\dotnet\contrast_security.yaml by default. The installer does not copy the YAML file if it already exists at the destination.

    Tip

    You can use the command line to access additional options supported by the .NET agent installer.

    If you are using another profiler in this environment, such as an APM like New Relic or AppDynamics, then you need to enable Contrast profiler chaining.

  4. You can further configure the .NET Framework agent using the .NET Framework YAML template.

  5. Use the application as you normally would and verify that Contrast sees your application.

    Note

    If there are some applications you don't need to analyze, or if you are trying to be lean on performance, consider using application pools to limit the number of applications instrumented.

    You can stop and start the agent to disable or enable analysis of your application.

Install the .NET Framework agent using command line

You can use the command line to access additional options supported by the .NET agent installer.

The .NET agent can be installed using the Windows UI, and uninstalled or repaired using standard Windows features (including the Programs and Features Control Panel and Powershell). However, you may want to use the .NET agent installer to perform these actions instead for certain scenarios such as automated scripting.

Use these commands for attended mode:

  • Install: ContrastSetup.exe

  • Uninstall: ContrastSetup.exe -uninstall

  • Repair: ContrastSetup.exe -repair

Use these commands for unattended or silent mode:

  • Install: ContrastSetup.exe -s -norestart

  • Uninstall: ContrastSetup.exe -uninstall -s -norestart

  • Repair: ContrastSetup.exe -repair -s -norestart

The .NET agent installer supports several additional options that are accessible when you use the command line for installation.

Option

Description

Example

StartTray

When set to 0, this suppresses the start of the tray application when agent installation is completed. This is recommended when installing the agent on Windows Server Core instances. The default is 1.

StartTray=0

PathToYaml

This specifies a custom YAML configuration file. The default is the contrast_security.yaml file located relative to the installer's location.

PathToYaml=c:\contrast_security.yaml

SERVICE_STARTUP_TYPE_MANUAL

This must be provided when installing, upgrading and repairing the agent. If set to 1, this option sets the Contrast service startup type to Manual. The default is 0 (Automatic Delayed Start).

SERVICE_STARTUP_TYPE_MANUAL=1

SUPPRESS_SERVICE_START

This must be provided when installing, upgrading and repairing the agent. If set to 1, this option suppresses automatically starting the service. The default is 0.

SUPPRESS_SERVICE_START=1

Tip

To install the .NET agent using scripts, you can use this command:

ContrastSetup.exe -s -norestart StartTray=0 PathToYaml=C:\Temp\custom.yaml

This command installs the .NET agent in silent and unattended mode, suppresses the start of the tray application, and uses a custom path to the YAML configuration file.

Start and stop the .NET Framework agent

To start the agent, and enable analysis, use one of these options:

  1. Select Windows Start > Services, then right-click on Contrast.NET Main Service and select Start.

  2. From an administrator command prompt, use:

    net start DotnetAgentSvc

Note

By default, the Contrast .NET Main Service is set to Startup Type: Automatic (Delayed Start). This means it automatically starts, either during installation or when Windows starts.

To stop the agent, and consequently disable Contrast instrumentation and analysis, use one of these options:

  1. Select Windows Start > Services, then right-click on Contrast.NET Main Service and select Stop.

  2. From an administrator command prompt, use:

    net stop DotnetAgentSvc

Important

Contrast automatically restarts IIS when you install the agent as well as any time that the .NET agent is stopped or started.

The .NET Profiling API requires that profiled processes be started with a profiler. Therefore, the .NET agent must restart IIS (and any IIS worker processes) to attach the Contrast profiler. This process is similar to how other profiling products (for example, memory or performance profilers) behave.

You may want to change the configuration of any web server monitoring tools that raise alarms when IIS restarts.

The .NET agent restarts IIS by stopping the Windows Process Activation Service (WAS), and then starts any previously running services that are dependent on WAS, such as World Wide Web Publishing Service (W3SVC). In some cases, users needed to manually configure service dependencies so that WAS-dependent services restart with IIS (for example, MSMQ Listener Adapter).

In this section: