Contrast agents are designed to require little to no interaction from the user to setup instrumentation. Once installed, the .NET agent automatically instruments ASP.NET applications deployed to IIS. Agent analysis is performed as applications are exercised by users (or by automated scripts or tests). You can view the results of the agent's analysis on the Contrast application.
The Contrast .NET agent consists of several components:
The background Windows Service (DotnetAgentService.exe) that prepares the environment for instrumentation and manages communication between agent components. This is the main service that controls agent behavior. You can disable Contrast's instrumentation and analysis by stopping the agent's background Windows service.
The .NET Profiler that instruments applications to weave in method calls out to agent sensors.
Sensors that gather security, architecture and library information.
The .NET Contrast Tray, a Windows system tray application that displays high-level information about the health of the agent.
Contrast automatically restarts IIS when you install the agent as well as any time that the .NET agent is stopped or started. 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 (e.g., memory or performance profilers) behave. You may want to change the configuration of any web server monitoring tools that raise alarms when IIS restarts. The .NET agent restarts IIS by stopping the Windows Process Activation Service (WAS), and then starts any previously running services that are dependent on WAS, such as World Wide Web Publishing Service (w3svc). In some cases, users needed to manually configure service dependencies so that WAS-dependent services restart with IIS (e.g., MSMQ Listener Adapter).
To start the agent, and consequently enable analysis, complete either of the following sets of instructions.
net start DotnetAgentSvc.
Note: By default, the Contrast .NET Main Service starts automatically when Windows starts as well as when the agent is first installed.
To stop the agent, and consequently disable Contrast instrumentation and analysis, complete either of the following sets of instructions.
net stop DotnetAgentSvc.
The .NET Contrast Tray is a Windows system tray application (ContrastTray.exe) that displays high-level information about the health of the agent. The following image demonstrates an example of a healthy agent.
Note: The Contrast Tray isn't required to be running to analyze applications with Contrast; the Contrast Tray exists only to provide status information about the agent. This information is useful when verifying that the agent is behaving as expected, particularly when the agent is first installed.
Agent Windows Service displays a green light when the Contrast Service has been installed correctly and is running
TeamServer displays a green light when the Agent Windows Service can communicate with the Contrast application. The most-common error that causes communication to fail is incorrect proxy settings.
IIS Sensors displays a green light when an application hosted on IIS has been loaded and instrumented. A yellow light is displayed when the agent has set up instrumentation, but IIS hasn't loaded an application yet.
IIS Express Sensors displays a green light when an application hosted on IIS-Express has been loaded and instrumented. A yellow light is displayed when the agent has set up instrumentation but IIS-Express hasn't loaded an application yet. A red light is displayed when environment variables have not been set for IIS-Express. See IIS-Express usage.
The Action tab provides high-level instructions for using the .NET agent; these instructions change based on the agent's state. For example, if the agent can't connect to Contrast, the Action tab provides details on the error and suggestions on how to resolve the problem.
The IIS tab displays a list of all web applications running on the IIS server. The name displayed matches the alias used by IIS to identify the application unless a custom application name has been specified. The URLs column displays the number of unique URLs (not including the query string) for the application that the agent has observed. The Last Activity column displays the time of the last request analyzed by the agent for that application. This tab is only displayed if IIS is installed.
The IIS AppPools tab displays a list of all application pools configured on the IIS server. This tab displays each application pool's configuration - architecture, pipeline mode, CLR version, identity - and whether or not applications in that application pool will be analyzed. Application pool analysis is configured using the .NET agent's Application Pool Filtering. This tab is only displayed if IIS is installed.
The IIS Express tab displays a list of all web applications set up to run on IIS Express. This tab is only displayed if IIS Express is installed.
The Console tab includes status and error messages that are useful for troubleshooting problems with the Contrast .NET agent.
A .NET framework application's compiled code is generally contained in .DLL files, while debug information is contained in .PDB files. These .PDB files contain symbol information that Contrast can use to tie stack trace frames to specific lines of code.
By default, the Debug build of web applications includes .PDB files; the Release build doesn't. However, most deployments of web applications use the Release build because deploying the Debug build can introduce some unnecessary risks. It's possible to include .PDB files in the Release build of a web application by changing a project setting.
Note: The inclusion of .PDB files in a web application's deployment is safe and doesn't include the risks associated with publishing a Debug build.
The following steps configure the build/package process for the Release configuration to include .PDB files in Visual Studio:
The .NET agent automatically instruments all ASP.NET applications deployed to IIS by default. There is no action required to setup instrumentation of IIS-hosted applications beyond installing the .NET agent and ensuring the agent's background Windows is running.
Users might want to exclude some applications from instrumentation for either of the following reasons:
In either case, you can use the .NET agent's application pool filtering feature.
Web applications hosted on IIS run on application pools. If you need to disable the .NET agent for specific application pools on an instance of IIS, configure a
agent.dotnet.app_pool_blacklist. When an application pool is blacklisted, the agent won't attach to any applications using that application pool, and there should be no performance impact for those applications.
Whitelisting and blacklisting are based on the application pool name. Application pool blacklists and whitelists also accept
* as a variable-length wildcard. ("AppPool*" will match "AppPool1", "AppPool_arb", etc.)
Note: Blacklisting an application takes precedence over whitelisting. Application pools that satisfy both lists won't be analyzed.
You can find the application pool that's running an application using the following methods:
Use IIS Manager:
appcmd list apps.
Use Contrast .NET Logs:
To disable the agent for a specific application, populate
agent.dotnet.app_pool_blacklist with the appropriate application pool in C:\ProgramData\Contrast\dotnet\contrast_security.yaml:
# Comma-separated list of application pools ignored by Contrast agent: dotnet: app_pool_blacklist: ExampleAppPoolName
If you need to only enable the agent for specific applications hosted by IIS, configure
agent.dotnet.app_pool_whitelist to only analyze certain application pools. If an application pool is whitelisted, the agent analyzes the matching pools. There should be no performance impact for any other applications.
To enable the agent for only specific application pools, populate
agent.dotnet.app_pool_whitelist with the appropriate application pool in C:\ProgramData\Contrast\dotnet\contrast_security.yaml:
# Comma-separated list of application pools exclusively profiled by Contrast agent: dotnet: app_pool_whitelist: ExampleAppPoolName
For more information on the standard configuration for the agent, see the configuration overview.
The .NET agent can analyze ASP.NET applications hosted on IIS-Express but it takes a little bit of work to enable instrumentation on IIS-Express. The Contrast tray displays a tab for IIS Express if IIS Express is installed on the server.
The Contrast Tray initially displays a Set Environment Variables button to enable instrumentation of IIS Express-hosted applications. Selecting this button sets environment variables for the current user so that any new IIS-Express process will load the .NET agent's profiler, and be instrumented and analyzed.
- IIS-Express process instances are commonly launched by other programs such as Visual Studio or a command window. You should restart these programs after setting these user environment variables. Any programs (such as Visual Studio) that were running before you set user environment variables will consequently launch IIS Express without the environment variables, and the IIS Express-hosted application won't be instrumented and analyzed.
- Setting user environment variables also causes any .NET applications launched by the user to load the Contrast Profiler. The Contrast Profiler will safely detach from any non-IIS/non-IIS Express process. Windows treats detachment of a profiler DLL as an error message in the Windows Event Log; however, you can safely ignore these errors.
Once you've set environment variables, the Contrast Tray displays a Remove Environment Variables button that you can use to disable Contrast analysis of IIS Express-hosted applications.
Any instrumented applications currently running on IIS Express are displayed in the IIS Express tab along with a count of the number of URLs (without the querystring) observed.
Use the Contrast .NET agent to analyze ASP.NET applications running on Azure Virtual Machines (VMs), Cloud Services, Mobile Services or Azure App Service (formerly Azure Web Sites). Follow the instructions below to set up the .NET agent in your environment.
Complete the following steps to install the .NET agent on an Azure VM: