Skip to main content

Install the .NET Core agent with the .NET Core agent for IIS installer

The .NET Core agent for IIS 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 Core 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-core). 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-core).

  • Adds the .NET Core agent’s native modules to IIS.

Before you begin

Before you begin, check the system requirements and supported technologies to be sure installation will work and ensure best performance.

Install the agent using Contrast

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

  2. Choose .NET Core in the Choose an agent dropdown menu.

  3. Select the link icon-download.svg.NET Core IIS agent installer under Install with IIS. A ZIP archive downloads.

  4. Extract the downloaded ZIP archive on the web server, and run contrast-dotnet-core-agent-for-iis-installer.exe. This installs the .NET Core agent for IIS.


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

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

  6. Copy the yaml file to C:\ProgramData\Contrast\dotnet-core if not already there.

  7. Restart IIS to pick up the changes.

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

Install the agent using command line

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

The .NET Core for IIS agent can be installed 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:contrast-dotnet-core-agent-for-iis-installer.exe

  • Uninstall:contrast-dotnet-core-agent-for-iis-installer.exe -uninstall

  • Repair:contrast-dotnet-core-agent-for-iis-installer.exe -repair

Use these commands for unattended or silent mode:

  • Install:contrast-dotnet-core-agent-for-iis-installer.exe -s SUPPRESS_RESTARTING_IIS=1

  • Uninstall:contrast-dotnet-core-agent-for-iis-installer.exe -uninstall -s SUPPRESS_RESTARTING_IIS=1

  • Repair:contrast-dotnet-core-agent-for-iis-installer.exe -repair -s SUPPRESS_RESTARTING_IIS=1

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





This option specifies the install directory for the agent files.

INSTALLFOLDER=C:Program Files\Contrast\dotnet-core


This option specifies the directory for Agent Explorer files.

AGENT_EXPLORER_INSTALLFOLDER="C:\Program Files\Contrast\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.



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



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

The default value is 0.


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



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.



This option specifies the directory for the upgrade service files.

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


The .NET Core agent for IIS 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 Core 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.