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

Check the system requirements and supported technologies to be sure installation will work and ensure best performance.
.NET Framework applications:
- If you are using the agent with self-hosted Web API and OWIN (outside of IIS), further configuration is needed.
- If you are using Windows 2008, a version of .NET Framework prior to 4.7.1 or if your application targets CLR2, you should use the Legacy .NET Framework agent installer.

Install the agent using Contrast

In the Contrast web application, select Add new.
Select the Application card.
Select one of these agents:
- .NET Framework
- .NET Core
Download the configuration file.
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
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.
Configure the agent with a YAML configuration file to set the authentication keys and any application-specific configuration.
- .NET Core: .NET Core YAML configuration file
- .NET Framework: .NET Framework YAML template.
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
Restart IIS to pick up the changes.
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.

In this section: