Skip to main content

.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. Select the Application card.

  3. Choose .NET Framework in the application language dropdown, then select IIS hosted and select the link to Download the agent and YAML configuration file.

  4. 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.

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

  6. 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 option specifies the install directory. Program files will be written to this directory. Defaults are dependent on OS variables.

INSTALLFOLDER="D:\Programs\Contrast"

AGENT_EXPLORER_INSTALLFOLDER

This option specifies the directory for Agent Explorer files.

AGENT_EXPLORER_INSTALLFOLDER="C:\Program Files\Contrast\agent-explorer"

DATAFOLDER

This option 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"

PathToYaml

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

PathToYaml=c:\contrast_security.yaml

SERVICE_STARTUP_TYPE_MANUAL

This option is required when you install, upgrade, and repair the agent. If you set the value to 1, this option sets the Contrast service startup type to Manual. The default value is 0 (Automatic Delayed Start).

SERVICE_STARTUP_TYPE_MANUAL=1

SUPPRESS_SERVICE_START

This option is required when you install, upgrade, and repair the agent. If you set the value to 1, this option automatically suppresses starting the service. The default value is 0.

SUPPRESS_SERVICE_START=1

SUPPRESS_RESTARTING_IIS

If you set the value of this option to 1, the installer does not restart IIS.

The default value is 0.

Note

  • Applications do not load the agent until IIS restarts.

  • Setting SUPPRESS_RESTARTING_IIS will prevent an auto-upgrade from running unless IIS does not have any active workers when the upgrade runs.

SUPPRESS_RESTARTING_IIS=0

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_AGENT_EXPLORER

If you don't want to install the Agent Explorer, set the value for this option to 0.

The default value is 1, which installs the Agent Explorer.

INSTALL_AGENT_EXPLORER=1

INSTALL_UPGRADE_SERVICE

If you don't want to install the agent upgrade service, set the value of this option to 0 . The default value is 1 which installs the agent upgrade service.

INSTALL_UPGRADE_SERVICE=1

UPGRADE_SERVICE_INSTALLFOLDER

This option specifies the directory for the 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 PathToYaml=C:\Temp\custom.yaml

This command installs the .NET agent in silent and unattended mode and uses a custom path to the YAML configuration file.

Important

Contrast automatically restarts IIS when you install the agent.

In this section: