.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 Introduction to .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:

  1. Go to the .NET agent download site and get the file matching your application's runtime and architecture:
    • .NET Framework (32-bit): newrelic-agent-win-x86-VERSION.zip
    • .NET Framework (64-bit): newrelic-agent-win-x64-VERSION.zip
    • .NET Core (32-bit): newrelic-netcore20-agent-win-x86-VERSION.zip
    • .NET Core (64-bit): newrelic-netcore20-agent-win-x64-VERSION.zip
  2. Unzip the agent folder in the desired location.
  3. Set environment variables for the process you wish to monitor.

    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.
    .NET Framework environment variables for manual install

    For .NET Framework, the following variables are required:

      COR_ENABLE_PROFILING=1
      COR_PROFILER={71DA0A04-7777-4EC6-9643-7D28B46A8A41}
      NEWRELIC_HOME=path\to\agent\directory
      COR_PROFILER_PATH=path\to\agent\directory\NewRelic.Profiler.dll
    
    .NET Core environment variables for manual install

    For .NET Core, the following variables are required:

      CORECLR_ENABLE_PROFILING=1
      CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}
      CORECLR_NEWRELIC_HOME=path\to\agent\directory
      CORECLR_PROFILER_PATH=path\to\agent\directory\NewRelic.Profiler.dll
    
  4. 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:

  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 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:

Scriptable installers (Windows only)

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.

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.

Scriptable installer for .NET Framework

To use the scriptable installer to install the .NET agent for a .NET Framework app:

  1. Ensure you have administrator rights for your Windows admin group. For more details on this, see the permissions documentation.
  2. 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.
  3. Unzip the package.
  4. Open a command shell and navigate into the unzipped package's folder.
  5. For a simple install with no options, use this command:

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

    install.cmd -LicenseKey YOUR_LICENSE_KEY [-NoIISReset] [-InstrumentAll] [-InstallPath PATH_TO_INSTALL]
    

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

Uninstalling the agent with the scriptable uninstaller:

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 Framework agent:

.\uninstall.cmd
Scriptable installer for .NET Core

Before installing the agent:

  • Understand the agent requirements, including the permissions requirements.
  • Note that admin rights in an elevated shell are required (specifically for selecting a custom log directory and performing an IISReset).

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 (e.g. 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:

  1. Ensure you have administrator rights for your Windows admin group. For more details on this, see the permissions documentation
  2. Download the .NET Core 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.
  3. Unzip the package in the desired location.
  4. Open a command shell and navigate into the unzipped package's folder.
  5. You can install the agent either locally or globally:
    Local install
    For a simple install, with no options, use this command:
    ./installAgent.ps1 -destination PATH -installType global -licenseKey YOUR_LICENSE_KEY \
    	[-appName "YOUR_APPLICATION_NAME" -logDir "PATH_TO_CUSTOM_LOG_LOCATION"]
    To install with one or more additional options, use the same command with desired options. For option descriptions, see table below.
    ./installAgent.ps1 -destination PATH -installType local -licenseKey YOUR_LICENSE_KEY \
    	[-appName "YOUR_APPLICATION_NAME" -logDir "PATH_TO_CUSTOM_LOG_LOCATION" -X86 -ResetIIS -Force]
    Global install
    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:
    ./installAgent.ps1 -destination PATH -installType global -licenseKey YOUR_LICENSE_KEY \
    	[-appName "YOUR_APPLICATION_NAME" -logDir "PATH_TO_CUSTOM_LOG_LOCATION"]
    To install with one or more additional options, use the same command with desired options. For option descriptions, see table below.
    ./installAgent.ps1 -destination PATH -installType local -licenseKey YOUR_LICENSE_KEY \
    	[-appName "YOUR_APPLICATION_NAME" -logDir "PATH_TO_CUSTOM_LOG_LOCATION" -X86 -ResetIIS -Force]

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

For more help