Skip to main content

Install the .NET agent with the .NET Windows installer

The .NET agent Windows installer is a normal Windows application installer built using standard MSI technology. It validates that the target server and 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 agent for IIS 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.

  • 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 .NET agent’s native modules 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.

    This service is responsible for communication with profiler and sensor components through local named pipes.

  • Starts the Agent Explorer application.

Before you begin

Install the agent using Contrast

  1. In the Contrast web application, select Add new.

  2. Select the Application card.

  3. Select one of these agents:

    • .NET Framework

    • .NET Core

  4. Download the configuration file.

  5. To download the agent, follow the instructions for the installation method you want to use:

    1. Azure App Service

    2. Using a container

    3. .NET agent with NuGet

    4. .NET Core: Manual installation

    5. .NET Framework: Web API and Owin

  6. Extract the downloaded ZIP archive on the web server and install it with this command:

    ContrastSetup.exe

    Tip

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

  7. Configure the agent with a YAML configuration file to set the authentication keys and any application-specific configuration.

  8. Copy the contrast_security.yaml file to the required location, if not already there:

    • .NET Core: C:\ProgramData\Contrast\dotnet-core

      <NOTE TO REVIEWERS: WILL THIS USE THE SAME LOCATION AS .NET FRAMEWORK INSTEAD OF A .NET CORE LOCATION?>

    • .NET Framework: C:\ProgramData\Contrast\dotnet

  9. Restart IIS to pick up the changes.

  10. 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 agent using command line

Use the command line to access additional options supported by the .NET agent installer.

You can install the .NET agent using the Windows interface, and uninstalled or repaired using standard Windows features (including the Programs and Features Control Panel and Powershell). However, you may want to use the Contrast Windows 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

INSTALLFOLDER

This option specifies the install directory for the agent files.

INSTALLFOLDER="C:Program Files\Contrast\dotnet"

AGENT_EXPLORER_INSTALLFOLDER

This option specifies the directory for Agent Explorer files.

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

INSTALL_AGENT_EXPLORER

<NOTE TO REVIEWERSL .NET CORE ONLY?>

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

DATAFOLDER

This option specifies the default location for agent log and configuration files.

DATAFOLDER=C:\ProgramData\Contrast\dotnet-core

PathToYaml

<.NOTE TO REVIWERS: NET FRAMEWORK ONLY?>

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

<NOTE TO REVIEWERS: .NET FRAMEWORK ONLY?>

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

<NOTE TO REVIEWERS: .NET FRAMEWORK ONLY?>

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

SKIP_IIS_MODULES

If you don't want to install the agent IIS modules, set the value of this option to 1.

The default value is 0, which installs the IIS modules.

SKIP_IIS_MODULES=1

USE_VIRTUAL_SERVICE_ACCOUNT

<NOTE TO REVIEWERS:NET FRAMEWORK ONLY?>

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

<NOTE TO REVIEWERS:.NET FRAMEWORK ONLY?>

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"

Installation notes

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

  • The .NET agent installer automatically restarts IIS when you install the agent for the first time. You may want to change the configuration of any web server monitoring tools that raise alarms when IIS restarts.

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