This document contains detailed descriptions of resources and procedures that are referenced in the .NET agent install procedures.
Important
This document is not meant to be read as a standalone document. For install instructions, see .NET agent install.
Microsoft's .NET profiler
New Relic's .NET agent relies on the Microsoft profiling API to report data from your .NET application.
.NET monitoring solutions other than New Relic can use this profiling API. But only one service can use the profiler at a time. This means that if you have used a .NET monitoring service in the past and haven't completely disabled/removed it, the profiler may still be in use, which will cause profiler conflicts when you try to enable the .NET agent.
.NET agent download library
The New Relic .NET agent download library contains install file packages that are referenced in specific install procedures. For more on these files, see the download library’s ReadMe file.
Zip files for manual .NET agent install (Windows)
To manually install the agent using a ZIP file, choose the correct file for the application you wish to monitor:
Go to the .NET agent download site and get the file matching your application's architecture (64-bit or 32-bit):
.NET Framework or .NET Core/.NET 5+ (32-bit): NewRelicDotNetAgent_VERSION_x86.zip
.NET Framework or .NET Core/.NET 5+ (64-bit): NewRelicDotNetAgent_VERSION_x64.zip
Unzip the agent folder in the desired location.
Set environment variables for the process you wish to monitor.
Caution
We do not recommend setting these environment variables globally. Setting these environment variables globally can cause all .NET processes running on the system to get instrumented and report to New Relic. If you are installing the agent manually, we expect that you have the means to set these environment variables only for the processes you wish to monitor.
For .NET Framework, the following variables are required:
Restart your application. If using IIS, restart IIS.
If your application is receiving traffic, data should appear within a few minutes. If it doesn't, see No data appears.
Need for custom instrumentation
After installing a .NET agent, most .NET application frameworks will automatically report data to your New Relic account. (See app framework compatibility: .NET Framework | .NET Core.)
If your .NET application uses an application framework that is not automatically instrumented, or if the app has no framework (like a console app), after the install you will need to manually set up instrumentation of your app. Here are the steps to do that:
Custom instrument your application to define what activity is reported to New Relic.
Install-related environment variables
A .NET agent install requires setting environment variables. For some install procedures (like for IIS-hosted .NET applications), these environment variables are set automatically. For other install procedures, you will have to manually set them. To see the required environment variables for both .NET Framework and .NET Core applications, see Environment variables.
For installations requiring you to manually set environment variables, you can also set other configuration options via environment variables. Here's a look at two that are commonly set:
License key. The environment variable for setting the is:
The scriptable installers are ZIP archives containing a PowerShell script for installing the .NET agent. There is a separate zip archive for .NET Framework versus .NET Core.
Important
We recommend using the MSI installer over the scriptable installer. If you want to automate your install, consider running the MSI installer from the command line.
Important
As of .NET agent version 10.0.0, the scriptable installers are no longer available. This documentation remains for customers who wish to use the scriptable installer for an older version.
To use the scriptable installer to install the .NET agent for a .NET Framework app:
Ensure you have administrator rights for your Windows admin group. For more details on this, see the permissions documentation.
Download the scriptable installer package for .NET Framework from the download site. By downloading or using one of these packages, you agree to and accept the license terms.
Unzip the package.
Open a command shell and navigate into the unzipped package's folder.
For a simple install with no options, use this command:
bash
$
.\install.cmd -LicenseKey YOUR_LICENSE_KEY
To install with one or more additional options, use the format below. See table below for a description of the install options.
If your application is receiving traffic, data should appear within a few minutes. If it doesn't, see No data appears.
Install options
Description
LicenseKey
Required. Your .
NoIISReset
Optional. Use this option to prevent the installer from initiating an IIS reset.
Important
If you use this option, you need to do an IIS reset manually before New Relic starts instrumenting any IIS-hosted applications.
InstrumentAll
Optional. By default, the .NET agent will instrument all IIS-hosted applications. Use this option to enable instrumentation of other types of .NET applications.
InstallPath
Optional. Use this option to choose a different installation location. The default install location is C:\Program Files\New Relic.
Uninstalling the agent with the scriptable uninstaller:
Tip
You can add the Force option to the uninstall script to force an uninstall without prompting to restart IIS.
Execute the following command to uninstall the .NET agent:
Note that admin rights in an elevated shell are required (specifically for selecting a custom log directory and performing an IISReset).
Caution
For security reasons, it is necessary to execute the installAgent.ps1 script as shown below, by prepending ./ to the script filename, rather than by prepending powershell to the script. If you execute the script by prepending powershell, and any of your supplied arguments (such as the install path or custom log path) have spaces in them, these arguments will be corrupted, which would lead to the agent being installed to a location other than the intended location, which could be unsecure.
To use the scriptable installer to install the .NET agent for a .NET Core application:
Ensure you have administrator rights for your Windows admin group. For more details on this, see the permissions documentation
Download the .NET agent's scriptable installer package from the .NET agent download site . By downloading or using one of these packages, you agree to and accept the license terms.
Unzip the package in the desired location.
Open a command shell and navigate into the unzipped package's folder.
You can install the agent either locally or globally:
For a simple install, with no options, use this command:
bash
$
./installAgent.ps1 -destinationPATH-installType global -licenseKey YOUR_LICENSE_KEY \
The global install will instrument all .NET Core processes on your system. Only choose the global install if you want all .NET Core processes monitored.
For a simple install with no options, use this command:
bash
$
./installAgent.ps1 -destinationPATH-installType global -licenseKey YOUR_LICENSE_KEY \
If your application is receiving traffic, data should appear within a few minutes. If it doesn't, see No data appears.
Install options
Description
Destination
Required. The location where the agent is installed. This can be an absolute or relative path. Wrapping quotes are required.
InstallType
Required. Determines whether this is a local (app-specific) or global (system-wide) install.
LicenseKey
Required. Your .
AppName
Optional. Sets the default application name associated with your agent installation.
LogDir
Optional. Sets a custom logging location for the agent. By default, the agent puts the logs directory in the install directory.
X86
Optional. Installs the 32-bit version of the agent rather than the 64-bit version. New Relic does not recommend installing the 32-bit version of the agent globally.
ResetIIS
Optional. Performs an iisreset after the installation.
Important
Only use this if your .NET Core app is hosted via an IIS reverse proxy.
Force
Optional. Forces the installation process to overwrite a previous install or to install into an existing folder.
Caution
This overwrites any configuration customizations. New Relic recommends backing up your configuration file and any custom instrumentation files prior to forcing an over-install.
Help
Optional. Displays usage information for this script.