Use the Agent

The Basics

How It Works

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.

IIS restart

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

Analysis

Start the agent

To start the agent, and consequently enable analysis, complete either of the the following sets of instructions.

Option one

  • Go to Windows Start, and select Services.
  • Right click on Contrast .NET Main Service, and select Stop

Option two

  • From an administrator command prompt, use net stop DotnetAgentSvc.

Note: By default, the Contrast .NET Main Service starts automatically when Windows starts as well as when the agent is first installed.

Stop the agent

To stop the agent, and consequently disable Contrast instrumentation and analysis, complete either of the the following sets of instructions.

Option one

  • Go to Start and select Services.
  • Right click on Contrast .NET Main Service and select Start.

Option two

  • From an administrator command prompt, use net start DotnetAgentSvc.

.NET Contrast Tray

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.

Status indicators

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

Tabs

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

Source Code Information

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.

Configuration

The following steps configure the build/package process for the Release configuration to include .PDB files in Visual Studio:

  • Open the web application's solution in Visual Studio.
  • Right click on the application's project and select Properties.
  • Select the Package/Publish Web tab.
  • Select the Release configuration from the Configuration dropdown.
  • Confirm that the box to Exclude generated debug symbols is not checked.
  • Save the project file.
  • Build and publish the web application using your normal deployment process.

IIS

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:

  • You don't need to gather security, architecture and library information for excluded applications.
  • The applications need to avoid Contrast's performance overhead. (This is especially important for resource-constrained servers.)

In either case, you can use the .NET agent's application pool filtering feature.

Application Pool Filtering

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

Find an Application Pool

You can find the application pool that's running an application using the following methods:

  • Internet Information Services (IIS) Manager
  • AppCmd.exe
  • Contrast .NET Logs

Use IIS Manager:

  • Start IIS Manager: %windir%\system32\inetsrv\InetMgr.exe.
  • Select a web application.
  • Click Basic Settings.
  • The application pool name is displayed in a form field. (See the image below.)

Use AppCmd.exe:

  • Run cmd.exe as an Administrator.
  • Navigate to C:\Windows\System32\inetsrv.
  • Enter the command appcmd list apps.
  • A list of applications and their associated application pools appear. (See the image below.)

Use Contrast .NET Logs:

  • Start the Contrast .NET agent.
  • Browse to an application.
  • In Windows, navigate to C:\ProgramData\Contrast\dotnet\LOGS.
  • Open the most recent Profiler log (Profiler_[AppPool]_XXXXXXXX_XX_XX_XX_XXX_XXXXX.log).
  • The application pool name is on the line that starts with ApplicationPool Name:.

Blacklist an Application Pool

To disable the agent for a specific application, populate ProcessBlacklist with the appropriate application pool in C:\Program Files\Contrast\dotnet\DotnetAgentService.exe.config:

<!--Comma-separated list of application pools ignored by Contrast-->
<add key="ProcessBlacklist" value=""/>

Whitelist an Application Pool

If you need to only enable the agent for specific applications hosted by IIS, configure a ProcessWhitelist 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 ProcessWhitelist with the appropriate application pool in C:\Program Files\Contrast\dotnet\DotnetAgentService.exe.config:

<!--Comma-separated list of application pools exclusively profiled by Contrast-->
<add key="ProcessWhitelist" value=""/>

For more information on the standard configuration for the agent, see the Configuration Overview.

IIS Express

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.

Notes:

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

Azure

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.

Azure Virtual Machines

Complete the following steps to install the .NET agent on an Azure VM:

  • Copy the .NET agent zip file to the Azure VM, and extract the archive.
  • Run the .NET agent installer (ContrastSetup.exe).
  • Browse to and use the application so that Contrast can analyze it.

Azure Cloud Services or Mobile Services

  • Copy the .NET agent zip file to the Cloud Service instance, and extract the archive.
  • Run the .NET agent installer (ContrastSetup.exe).
  • Browse to and use the application normally so that Contrast can analyze it.

Azure Web Apps

Follow the instructions to install the agent for Azure App Service via Nuget or Azure Portal Extensions.