.NET Framework agent installer for Windows

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.

  • Adds the agent's Native Module to IIS. The Native Module registers the agent’s profiler component with IIS through environment variables. This causes the CLR to load the agent’s profiler, which is responsible for instrumenting analyzed applications.

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

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

Note

Install the .NET Framework agent using Contrast:

Install the .NET Framework agent using Contrast

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

  2. Choose .NET Framework in the application language dropdown, 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.

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

    • 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 agent using the .NET Framework YAML template.

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

    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.

Install the .NET Framework agent using command line

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

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 Framework agent installer for Windows 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 Framework agent installer for Windows supports several additional options that are accessible when you use the command line for installation.

Option

Description

Example

INSTALLFOLDER

This specifies the install directory. Program files will be written to this directory. Defaults are dependent on OS variables.

INSTALLFOLDER="D:\Programs\Contrast"

DATAFOLDER

This specifies the data directory. Logs and the contrast_security.yaml file will be written to this directory. Defaults are dependent on OS variables.

DATAFOLDER ="D:\Data\Contrast"

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

USE_VIRTUAL_SERVICE_ACCOUNT

Run the agent service under a restricted virtual service account. Configures the service to run as the NT Service\DotnetAgentSvc virtual account instead of SYSTEM.

USE_VIRTUAL_SERVICE_ACCOUNT=0

INSECURE_YAML_FILE

Restrict edits to the contrast_security.yaml file of non-elevated users.

INSECURE_YAML_FILE=0

INSTALL_UPGRADE_SERVICE

Set to 0 to not install the agent upgrade service. Default value is 1.

INSTALL_UPGRADE_SERVICE=1

UPGRADE_SERVICE_INSTALLFOLDER

Specify the location where the installer will place upgrade service files.

UPGRADE_SERVICE_INSTALLFOLDER="C:\Program Files (x86)\Contrast\upgrade-service"

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.

Important

Contrast automatically restarts IIS when you install the agent.