.NET agent install resources

This document contains detailed descriptions of resources and procedures that are referenced in the New Relic .NET agent install procedures.

This document is not meant to be read as a standalone document. For install instructions, see the introduction to .NET agent installation.

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.

MSI installer (for .NET Framework only)

The MSI (Microsoft installer) tool is the recommended way to install the .NET Framework agent. There is no MSI installer for the .NET Core agent.

Instructions on how to use the MSI are in the .NET Framework agent install instructions. You can use the MSI as an automated install wizard or via the command line or in automated install scripts.

Tips for using the MSI install wizard:

  • If you are changing an existing installation using the MSI install wizard, select the Change option.
  • Input your New Relic license key.
  • Give your application a descriptive name.
  • Instrument all option: This sets environment variables that allow the New Relic agent to see .NET applications. For IIS-hosted applications, this option can be left disabled because IIS-hosted applications are automatically detected and targeted. For applications not using IIS, or using IIS as a reverse proxy (as with an ASP.NET Core app targeting .NET Framework), you can choose one of these options:

Other options when using the MSI installer:

Use MSI via command line or in a script

Here is the command to perform a new installation of the agent using the MSI. (For changes to an existing installation, use the ADDLOCAL command.) Replace the highlighted sections with user-specific 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 Framework agent with default options (described 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 all available options (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

ProgramsFeature (default)

Required. This is the agent itself.

IISRegistryFeature (default) Required. This identifies the registry keys used to attach the .NET profiler to the application. Without this, the .NET agent will not work for an IIS-hosted app.
ApiFeature Include this option if you want to use .NET agent API calls. This allows for custom instrumentation.
AllAppsEnvironmentFeature This setting is the equivalent of using Instrument all in the MSI install wizard. For more on this, see Instrument all.
Set environment variables on a per-process level

When using the MSI, you also have the option of setting environment variables on a per-application/process basis. This is an alternative to using the MSI's Instrument all option (or the equivalent AllAppsEnvironmentFeature option).

One reason you might set environment variables on a per-application process is that setting system-wide environment variables means that logs will be created for every .NET process the agent has access to.

How you set the environment variables will depend on your setup and application framework. For example, if you run your processes from the command line or in a script, you can define the environment variables at that point.

Here's an example for setting the environment variables in the web.config file of an ASP.NET Core app targeting .NET Framework:

Example for ASP.NET Core app targeting .NET Framework

If you use ASP.NET Core Module to run your application behind IIS, you can set the environment variables in the web.config file, under the aspNetCore section. Here's an example of that section with the environment variables in place:

<aspNetCore processPath=".\MyApp.exe" 
        stdoutLogEnabled="false" 
        stdoutLogFile=".\logs\stdout">
<environmentVariables>
     <environmentVariable name="COR_ENABLE_PROFILING" value="1" />
      <environmentVariable name="COR_PROFILER" value="{71DA0A04-7777-4EC6-9643-7D28B46A8A41}" />
      <environmentVariable name="NEWRELIC_INSTALL_PATH" value="C:\Program Files\New Relic\.NET Agent" />
</environmentVariables>
</aspNetCore>

Target applications (for .NET Framework only)

For an application monitored by New Relic's .NET Framework agent to report data, there are two things that must be true:

  • Certain environment variables must be present: these tell the Microsoft .NET profiler to allow the New Relic agent to see when .NET applications start up.
  • The applications you want to monitor must also be specifically "targeted." This can be done in several ways, including via the New Relic .NET agent config or the application’s config file.

For applications using IIS, the MSI install process does the second step automatically (for how to override this, see Exclude apps). If you are not using IIS, or if you use IIS via reverse proxy (as is done with an ASP.NET Core app that targets .NET Framework), you must do the targeting step manually with one of the application-targeting procedures.

Targeting applications is not necessary for the .NET Core agent; once the correct environment variables are set, the agent will report data for all .NET applications it has access to.

NuGet package

NuGet is the package manager for .NET. New Relic has a NewRelic.Agent NuGet package that will install the .NET agent (the 64-bit Framework agent or the Core agent) when you build your .NET application.

Using NuGet to install the .NET agent involves the same basic steps described in the install process overview. The exact process will vary depending on your environment (for example, for Azure Service Fabric, the environment variables must be set in the ServiceManifest.xml file). Instructions for using NuGet are in specific install instructions

Required environment variables:

.NET Framework

Environment variables for applications targeting .NET Framework (including .NET Core apps that target .NET Framework) include:

COR_ENABLE_PROFILING = 1
COR_PROFILER = {71DA0A04-7777-4EC6-9643-7D28B46A8A41}
COR_PROFILER_PATH = APP_DEPLOYMENT_DIRECTORY\newrelic\NewRelic.Profiler.dll
NEWRELIC_HOME = APP_DEPLOYMENT_DIRECTORY\newrelic
NEW_RELIC_LICENSE_KEY = YOUR_LICENSE_KEY
NEW_RELIC_APP_NAME = YOUR_APP_NAME
.NET Core

Environment variables for Windows:

CORECLR_ENABLE_PROFILING = 1
CORECLR_PROFILER = {36032161-FFC0-4B61-B559-F6C5D41BAE5A}
CORECLR_PROFILER_PATH = APP_DEPLOYMENT_DIRECTORY\newrelic\NewRelic.Profiler.dll
CORECLR_NEWRELIC_HOME = APP_DEPLOYMENT_DIRECTORY\newrelic
NEW_RELIC_LICENSE_KEY = YOUR_LICENSE_KEY
NEW_RELIC_APP_NAME = YOUR_APP_NAME

Environment variables for Linux:

CORECLR_ENABLE_PROFILING = 1
CORECLR_PROFILER = {36032161-FFC0-4B61-B559-F6C5D41BAE5A}
CORECLR_PROFILER_PATH = APP_DEPLOYMENT_DIRECTORY/newrelic/libNewRelicProfiler.so
CORECLR_NEWRELIC_HOME = APP_DEPLOYMENT_DIRECTORY/newrelic
NEW_RELIC_LICENSE_KEY = YOUR_LICENSE_KEY
NEW_RELIC_APP_NAME = YOUR_APP_NAME

The scriptable installer (Windows only)

The scriptable installer is a zip archive containing a PowerShell script for installing the .NET agent (both Framework and Core).

Everything you can do with the scriptable installer can be done by creating a script using other methods (for example, using the MSI for a .NET Framework agent install script, or using the .NET Core zip file in an install script).

Instructions for using the scriptable installer are in specific install instructions. Options available when using the scriptable installer:

Options for .NET Framework

Options available when using the scriptable installer to install the .NET Framework agent:

Install options Description
LicenseKey Required. Your New Relic license key.
NoIISReset

Optional. Use this option to prevent the installer from initiating an IIS reset.

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.
Options for .NET Core agent

Options available when using the scriptable installer to install the .NET Core agent:

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 New Relic license key.
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.

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.

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.

ASP.NET Core framework-targeting

ASP.NET Core applications can target either .NET Core or .NET Framework. If your ASP.NET Core application targets .NET Framework, you must use the .NET Framework agent.

To determine what framework your ASP.NET Core application targets:

  1. Look in the .csproj file, which is located in the root folder of your project.
  2. See what the <TargetFramework> value is. If it's netcoreapp2.0, then your application is likely supported by the .NET Core agent. If it's a .NET Framework version (such as net452), you will need to use the .NET Framework agent, version 8.1 or higher.

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:

  1. Follow the relevant install instructions for your application and framework.

  2. 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 Framework 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 the .NET Framework agent and the .NET Core agent, 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:

For more help