Install .NET agent for Windows

Our .NET agent auto-instruments your code so you can start monitoring applications.

Install overview

The install instructions in this document are for a standard .NET agent installation on Windows. However, some setups have specific caveats and instructions, which you should read first:

The latest version of the .NET agent supports .NET Framework 4.5 and higher. If you have legacy applications you wish to monitor, see support for earlier .NET Framework versions.

Install the agent for IIS applications with our guided install

Our guided install creates a customized CLI command for your environment that downloads and installs the .NET agent for Windows IIS applications.

First, you need a New Relic account (It's free, forever!). Then, start the appropriate guided install. If your account reports data through our EU datacenter, use the EU Guided install.

Get an account

Guided install

EU guided install

In addition to the .NET agent, you can use the CLI to install and use our infrastructure agent to discover other applications, infrastructure, and log sources running in your environment and recommend which ones should be instrumented. The install automates the configuration and deployment of each system you choose to instrument.

Download and install the agent

To install the .NET agent:

Ensure you have admin rights for your Windows admin group. For more on this, see permissions documentation.
Download the installer that matches your system architecture:
- 64-bit
- 32-bit
Run the install wizard. Tips for using the install wizard:
- When prompted, input your New Relic license key.
- Consider leaving Instrument all disabled if you will only be monitoring applications hosted with IIS. Otherwise, enable Instrument all and follow additional instructions to enable the agent for your application.
- If you are changing an existing installation using the install wizard, select the Change option.
- Optional: you can also run the installer via the command line or from a script. This can be useful for automating your agent install.
For each application you wish to monitor, give your application a meaningful name. Make sure to review the steps on Name your .NET application for information on setting your app name.
If your application is short-lived (existing for less than 60 seconds), it will require configuration or it won't report data.
Restart affected applications. 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.

Run MSI via command line or from a script

Important

This section describes a command-line alternative to the standard install procedure.

Instead of using the MSI install wizard, you can run the MSI from the command line or from a script. This can be useful for automating your agent install.

Here is the command to perform a new agent install using the MSI installer. (For changes to an existing installation, use the ADDLOCAL command.) Replace the highlighted sections with relevant values.

msiexec.exe /i C:\PATH_TO\newrelic-agent-win-x86-VERSION.msi /qb NR_LICENSE_KEY=YOUR_LICENSE_KEY INSTALLLEVEL=1

The INSTALLLEVEL can be either 1 or 50:

1: Installs .NET agent with default options (described in table below). If your application is not hosted on IIS or uses IIS as a reverse proxy, you should use option 50.
50: Installs the agent with InstrumentAllNETFramework enabled (described below).

Instead of using the INSTALLLEVEL presets, you can customize which features to install with the ADDLOCAL command shown below. This is also the command you'd use to update an existing installation.

msiexec.exe /i C:\PATH_TO\newrelic-agent-win-x86-VERSION.msi /qb NR_LICENSE_KEY=YOUR_LICENSE_KEY ADDLOCAL=OPTION_1, OPTION_2

Available options are:

Option	Details
`NETFrameworkSupport`	Enabled by default. This identifies the registry keys used to attach the .NET profiler to a .NET Framework application. Without this, our .NET agent won't work for an IIS-hosted .NET Framework app.
`NETCoreSupport`	Enabled by default. This identifies the registry keys used to attach the .NET profiler to a .NET Core application. Without this, the .NET agent will not work for an IIS-hosted .NET Core app.
`InstrumentAllNETFramework`	This will result in all .NET Framework applications being instrumented by setting global environment variables. This setting is the equivalent of selecting Instrument all in the MSI install wizard.
`StartMenuShortcuts`	Enabled by default. Adds several useful shortcuts to your start menu.
`ASPNETTools`	Enabled by default. Adds the ASP.NET cache flush tool which, when run, clears out some .NET temporary files and restarts IIS.

Enable the agent for apps not in IIS

If the application you want to monitor is not hosted in IIS, you will follow the standard install procedure but in addition you must explicitly enable the agent for that application. Enabling the agent differs for .NET Framework and .NET Core applications.

When following the standard install procedure, we recommend that you enable Instrument all.

Enable for .NET Framework

Enable the agent for your application with one of the following methods:

In the application's config file, add a new appSetting with a key named NewRelic.AgentEnabled and a value of true. For example, if the application name is DataServices.exe, edit DataServices.exe.config to:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="NewRelic.AgentEnabled" value="true" />
    <add key="NewRelic.AppName" value="DataServices" />
  </appSettings>

You can use the newrelic.config file (either global or local), to choose what applications to monitor. In the configuration file, add an instrumentation element with a child application element for each application. In the instrumentation element, provide the base file name, with extension, you want to instrument (for example, <application name="DataServices.exe" />).

For example:

<instrumentation>
    <applications>
      <application name="BusinessLogicServices.exe" />
      <application name="DataServices.exe" />
    </applications>
</instrumentation>

You can use a local newrelic.config file to monitor an application:

Place the newrelic.config file in the directory containing the application's executable file.

Set the agentEnabled attribute to true.

For example:

<configuration xmlns="urn:newrelic-config"
  agentEnabled="true">

Enable for .NET Core

For .NET Core, you must configure your application to be monitored by setting the following environment variable:

CORECLR_ENABLE_PROFILING=1

We recommend setting the environment variables for each application you want to instrument. If you set them globally, you might instrument .NET processes other than your apps.

Tip

Here are a few ways you can set this environment variable per process, rather than system-wide.