.NET

Supported Technologies

Confirm that the tCell agent supports your .NET configuration, as shown below:

Version **App ServersWeb FrameworksOSMemoryPipeline ModeAuthentication Frameworks
4.5+
*CLR 4
IIS 7.0+Web Forms
*MVC 4 & 5
WCF
Web API 1 & 2
Windows Server 2008 R2 or later32-bit
64-bit
Integrated OnlyLogin hooks only

.NET Support Legend

* - For WCF, there is no route support

** - For .NET 5, use the .NET Core agent

Prerequisites

Installation

Get the Config File

  1. Click on "tCell Admin" in top navigation bar
  2. Create a new API Key
  3. Click "Download Agent"
  4. Select ".NET" agent
  5. Download either the zip or the msi file as desired
  6. Click "Download Config File" to download the agent's config file (which is prepopulated with the application and key information)

Install the agent

  1. Run the installer (.msi) and follow the instructions. This will install the agent and put the required files in the directory you specify. (default C:\Program Files\Rapid7, Inc\tCell .NET Agent). Consider also whether to enable OS commands and Local Files.
  2. Place the "tcell_agent.config" file in the root folder of your application.
  3. If you have more than 1 application running on the same IIS you only need to add a configuration file and place it in the root directory of the other applications (To be able to track different applications you should create a new application in tCell).
  4. Open a command prompt as administrator and run the command "iisreset" to restart the IIS. Your application is now protected by tCell!

OS Commands and Local Files

.NET agent supports both OS Command and Local Files feature support. This is done using the .NET profiling API. There is a .NET Profiling API system limitation that only one profiler can profile a program at a time. You must therefore disable existing tools that use the .NET profiling API before you can enable it for tCell agent.

If using the .msi installer to install the .NET agent, select the Code Instrumentation option during the installation process.

If running the agent installation as part of your CI/CD pipeline, use CLI arguments to install the tCell .NET agent with Code Instrumentation as follows:

msiexec.exe /i tcell-dotnetagent-2.2.3.0.msi ADDLOCAL=ALL /qn

Use ADDLOCAL=ALL

If you use msiexec.exe /i tcell-dotnetagent-2.2.3.0.msi or tcell-dotnetagent-2.2.3.0.msi to install the agent, you're not including the OS Command/LFI feature. To do so, include ADDLOCAL=ALL in your command line.

Prevent IIS recycling on IIS 7.5 or later

If you’re running IIS 7.5 or later, IIS will recycle your application if it's idle for 20 minutes or longer. When this happens, the agent will unload, stop running, and will show as offline in the tCell console. If a request comes in, the agent will start again.

If you don't want IIS to recycle the application when it's idle, you can change your application’s Start Mode and Idle Timeout for your application pool. Note that IIS will still recycle based on its regular recycle schedule. By default, this is set to 1740 minutes, or 29 hours.

To change your Start Mode and Idle Timeout:

  1. Go to advanced settings for your application pool by right clicking on you application pool and selecting advanced settings
  2. Set the Start Mode to AlwaysRunning, which is found under “General”
  3. Set the Idle Timeout (in minutes) to 0. This can be found under Process Model.

Troubleshooting

Installer

For .Net agent version 2.2.3 and above, there is an installer log located at C:\ProgramData\Rapid7, inc\tCell .Net Agent\InstallLog\ that can be used for debugging.

Log directory

The default log directory for .Net Agent version 2.2.0 and lower is [ApplicationDirectory]\Tcell\Logs

The default log directory for .Net Agent version 2.2.1 and greater is C:\ProgramData\Rapid7, inc\tCell .NET Agent\[ApplicationName]\Logs , if that fails it will fallback to the 2.2.0 directory.

Startup errors

To enable startup error logging set the TCELL_AGENT_STARTUP_ERROR_LOGGING environment variable to true or specify a valid path. This flag will create a file called tcell_critical_error.log in the root folder of the application running or at the path specified if there's an error at startup.

Note: this will write all startup errors for all applications to this file, so if there are a large number of applications and large number of errors, one may have to scan throughout the file to find application specific error messages.

Log levels

Valid log levels are:

  • ERROR
  • WARN
  • INFO (default)
  • DEBUG
  • TRACE

The preceding list indicates the precedence among the levels, from top to bottom. When you enable a log level, the higher log levels are also enabled. For example, if you enable WARN, then ERROR is also enabled.

When a log file becomes full, logging continues in a new log file.

Change log level

To change via environment variables, use the TCELL_AGENT_LOG_LEVEL and TCELL_AGENT_LOG_ENABLED environment variables.

Alternatively, one can enable via the server agent config by adding logging_options json snippet like:

server_agent.config snippet
1
"logging_options": {
2
"enabled": true, // Enable/Disable logging
3
"level": "DEBUG" // DEBUG, INFO, WARN, ERROR
4
}

Event Viewer

If no logs appear in any directory, check the event viewer and look for Errors under application.