Install the .NET agent on Windows

You need Administrator rights in your Windows admin group to install the New Relic .NET agent. For more information, see the permissions documentation for the .NET Framework agent or .NET Core 2.0 agent.

You can install the New Relic .NET agent to instrument .NET Framework or .NET Core 2.0 apps. The .NET Framework and .NET Core 2.0 agents are separate installs and can live side-by-side on the same server. Follow the relevant installation procedures for:

To make sure you are using the most current version, refer to the .NET agent release notes, and update your .NET agent as needed.

Install the .NET Framework agent (standard)

To install the Framework agent by using the standard installer wizard:

  1. Verify that you meet the compatibility and requirements for the .NET Framework agent.
  2. Download and run the appropriate install package for your architecture:

    If you want to instrument your app and it runs on Microsoft .NET Framework version 4.0 or earlier, you must run a version of New Relic's .NET agent prior to 7.0. For more information and download procedures, see Technical support for .NET frameworks 4.0 or earlier.

  3. When prompted, enter your New Relic license key.
  4. To monitor non-IIS applications, select the Instrument all option.

  5. Give your app a meaningful name.
  6. Restart any affected applications. For IIS-hosted applications, perform a command-line iisreset.

As long as your app is receiving traffic, data should appear within a few minutes. If not, follow the troubleshooting procedures.

Install the .NET Framework agent (command line)

If you prefer to install via the command line, you can also install the agent "silently." Follow this procedure, or put the commands in a script to fully automate your installation.

  1. Verify that you meet the compatibility and requirements for the .NET Framework agent.
  2. Download the appropriate install package for your architecture:
  3. From the command line, use one of the following methods to finish the .NET Framework agent installation:

    Manual install with default agent features

    Setting INSTALLLEVEL=1 installs the .NET Framework agent with default options:

    1. Use the command prompt to install the agent, replacing the path to the install package and inserting your license key:

      32-bit:

      msiexec.exe /i C:\PATH_TONewRelicDotNetAgent_x86.msi /qb NR_LICENSE_KEY=LICENSE_KEY INSTALLLEVEL=1

      64-bit:

      msiexec.exe /i C:\PATH_TONewRelicDotNetAgent_x64.msi /qb NR_LICENSE_KEY=LICENSE_KEY INSTALLLEVEL=1
    2. Restart IIS to complete the installation process.
    Manual install with all agent features

    Setting INSTALLLEVEL=50 installs the .NET Framework agent with all optional packages:

    1. Use the command prompt to install the agent, replacing the path to the install package and inserting your license key:

      32-bit:

      msiexec.exe /i C:\PATH_TONewRelicDotNetAgent_x86.msi /qb NR_LICENSE_KEY=LICENSE_KEY INSTALLLEVEL=50

      64-bit:

      msiexec.exe /i C:\PATH_TONewRelicDotNetAgent_x64.msi /qb NR_LICENSE_KEY=LICENSE_KEY INSTALLLEVEL=50
    2. Restart IIS to complete the installation process.
    Manual install and customize features

    You can customize which agent features to install with the ADDLOCAL option:

    ADDLOCAL Option Feature Details

    ProgramsFeature (default)

    Be sure to include this option. This is the agent itself.

    IISRegistryFeature (default) Be sure to include this option; otherwise the .NET agent will not work for IIS apps. This identifies the registry keys used to attach the profiler to the app.
    ApiFeature Include this option if you want to use any of the API calls to the agent itself, such as custom instrumentation.
    AllAppsEnvironmentFeature Include this option if you want to monitor non-IIS applications; for example, console apps.
  1. Use the command prompt to install the agent, replacing the path to the install package, inserting your license key, and specifying which features you want to install:

    32-bit:

    msiexec.exe /i C:\PATH_TONewRelicDotNetAgent_x86.msi /qb NR_LICENSE_KEY=LICENSE_KEY ADDLOCAL=OPTION_1, OPTION_2

    64-bit:

    msiexec.exe /i C:\PATH_TONewRelicDotNetAgent_x64.msi /qb NR_LICENSE_KEY=LICENSE_KEY ADDLOCAL=OPTION_1, OPTION_2
  2. Restart IIS to complete the installation process.

As long as your app is receiving traffic, data should appear within a few minutes. If not, follow the troubleshooting procedures.

Install the .NET Core 2.0 agent

Use one of the following methods to install the .NET Core 2.0 agent on Windows:

Scriptable installer
You can install the .NET Core 2.0 agent with a scriptable installer.
zip file

If using AspNetCoreModule (ANCM or AspNetCoreModule), you must use global environment variables.

For all others, New Relic recommends that you set environment variables for each application that you want to instrument. This avoids unintentionally instrumenting .NET Core 2.0 processes other than your apps.

  1. Verify that you meet the compatibility and requirements for the .NET Core 2.0 agent.
  2. Download the .NET Core 2.0 agent from the download site.
  3. Unzip the agent folder to any location that does not currently contain an agent.
  4. Ensure that folder has write access for the user that your .NET Core 2.0 application is running under.
  5. Set the following environment variables to enable instrumentation:

    CORECLR_ENABLE_PROFILING=1
    CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}
    CORECLR_NEWRELIC_HOME=PATH\TO\INSTALL
    CORECLR_PROFILER_PATH=%CORECLR_NEWRELIC_HOME%\NewRelic.Profiler.dll
    NEW_RELIC_LICENSE_KEY=YOUR_LICENSE_KEY
  6. Restart your apps (and IIS if using IIS as a reverse proxy via the AspNetCoreModule).

As long as your app is receiving traffic, data should appear within a few minutes. If not, follow the troubleshooting procedures.

Install the .NET Framework and Core 2.0 agents on the same system

You can install the .NET Core 2.0 and Framework agents on the same system, with the following requirements:

  • Separate directories: You must install the .NET Core 2.0 and .NET Framework agents in different directories.
  • Environment variables: The required environment variables are different for the .NET agents. Ensure that you set the environment variables by following the installation procedures for .NET Framework and .NET Core 2.0.

For more help

Recommendations for learning more: