Install .NET Framework agent

This document explains how to install and enable the New Relic APM .NET Framework agent (not the .NET Core agent).

Get started with the .NET Framework agent

Before installing the agent, some recommendations:

Install procedures for specific setups:

Install with MSI (recommended)

The following instructions are for installing the .NET Framework agent on a fully supported application framework (which includes ASP.NET) with the MSI installer:

  1. Ensure you have admin rights for your Windows admin group. For more on this, see permissions documentation.
  2. Go to the .NET agent download site and get the MSI file that matches your system:

    • 32-bit: newrelic-agent-win-x86-VERSION.msi
    • 64-bit: newrelic-agent-win-x64-VERSION.msi
  3. Run the MSI install wizard. Optional: you can also use the MSI via the command line or in a script.

    Recommendations for MSI settings:

  4. If your application is short-lived (existing for less than 60 seconds), it will require configuration or it won't report data.
  5. 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.

Install with MSI (with manual application targeting)

These instructions are for installing the .NET Framework agent for either:

  • A .NET Framework application not hosted on IIS

    OR

  • An ASP.NET Core application that targets .NET Framework

Before installing the agent, we recommend reading the install overview to understand some basic install concepts.

  1. Ensure you have admin rights for your Windows admin group. For more on this, see permissions documentation.
  2. Go to the download site and get the MSI file that matches your system:

    • 32-bit: newrelic-agent-win-x86-VERSION.msi
    • 64-bit: newrelic-agent-win-x64-VERSION.msi
  3. Run the MSI install wizard. Optional: you can also run the MSI via the command line or in a script.

    Recommendations for MSI configuration:

  4. Select the applications you want to monitor using one of the app-targeting procedures below. For more context, see application targeting.

    Enable via application config file

    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>
    
    Enable by app name via newrelic.config (global or local)

    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>
    Enable via placement of local newrelic.config file

    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">
    
  5. If using IIS, restart it.
  6. For applications using frameworks that New Relic doesn't automatically instrument, or for stand-alone apps (like a console app), you must custom instrument your application.
  7. If your application is short-lived (existing for less than 60 seconds), it won’t report data. You will need to configure it.

If your application is receiving traffic, data should appear within a few minutes. If it doesn't, see No data appears.

Install with NuGet

The NewRelic.Agent NuGet package places the New Relic agent in your application build's output directory so that the agent runs when the application is deployed.

Before installing the agent using NuGet, understand these important points:

  • A 64-bit system is required to use NuGet for a .NET agent install.
  • In order to configure environment variables and directory permissions, you must have access to the systems where you are deploying your applications. (The MSI install process is recommended because it's simpler.)
  • If you're using NuGet to update an existing .NET agent, this will overwrite previously made changes to newrelic.config. To preserve changes, first save the config file outside of your project, then restore it after updating.

Here's an example of using NuGet via Visual Studio to install the .NET Framework agent:

  1. Open your Visual Studio solution, or create a new one by selecting File > New > Project. For multi-project solutions, be sure to select the correct project (for example, a specific website project).
  2. Open the Package Manager console by selecting Tools > Library Package Manager > Package Manager Console. Set your project as the default project.
  3. From the Package Manager command prompt, type Install-Package NewRelic.Agent and press Enter. When you build your project, the .NET agent folder will be copied to your build output directory.
  4. Set environment variables (below) and any other necessary configuration. How to do this will vary, depending on your environment and system.

    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
    

If your application is receiving traffic, data should appear within a few minutes. If it doesn't, see No data appears.

Install for WCF applications

For self-hosted WCF applications (hosted as custom Windows Service, a console app, or a Windows Forms app) see Install for applications not hosted on IIS.

To install the .NET Framework agent on IIS-hosted WCF apps:

  1. Install the latest .NET Framework agent.
  2. Ensure you give each WCF app a descriptive name.
  3. Enable or disable ASP.NET compatibility mode depending on which type of events you want monitored:

    ASP.NET pipeline events and WCF events

    When ASP.NET compatibility mode is enabled, the .NET agent instruments ASP.NET pipeline events as well as WCF events. In this mode, the agent provides you with a full view of your application stack.

    Only WCF events

    When ASP.NET compatibility mode is disabled, the .NET agent only instruments WCF events. Any activity that occurs as part of the ASP.NET pipeline will not be captured, such as agent API calls that are made outside of a WCF transaction. In addition, cross application traces are not supported when ASP.NET compatibility mode is disabled.

If your application is receiving traffic, data should appear within a few minutes. If it doesn't, see No data appears.

Install with scriptable installer (Windows)

The scriptable installer package is a zip archive containing a PowerShell script for installing the .NET agent on a Windows system.

You can also use the MSI via the command line and in scripts; the MSI is the recommended install process.

For more details about this tool, see the install resources.

To install the .NET Framework agent with the scriptable installer:

  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 the Framework agent 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. For option descriptions, see Scriptable installer 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.

For more help

Recommendations for learning more: