.NET Framework: Install agent and define target applications

This document contains procedures for installing New Relic's .NET Framework agent for these situations:

  • Applications not using IIS
  • ASP.NET Core app targeting .NET Framework

Recommended: Before following these instructions, first read the .NET agent install overview.

.NET Framework agent install

Here are instructions for installing the New Relic .NET Framework agent for 1) applications that don't use IIS, or for 2) ASP.NET Core applications targeting .NET Framework.

  1. To ensure you're using the most relevant install procedures, first read the .NET agent install overview.
  2. Verify your application meets the .NET Framework agent requirements.
  3. Go to the download site and download the .msi file that corresponds to your architecture:

    • 32-bit: newrelic-agent-win-x86-VERSION.msi
    • 64-bit: newrelic-agent-win-x64-VERSION.msi
  4. Run the MSI installer. Some tips and options for using the MSI:

    • You can run the MSI as an auto-install wizard, or use it via the command line or in scripts.

      Use MSI via command line or script

      Here is the command to install the agent via MSI. 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 (listed below). If you choose this, you must set application-specific environment variables.
      • 50: Installs the agent with all available options (listed below).

      You can also customize what agent features to install with this command:

      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 profiler to the app. Without this, the .NET agent will not work for IIS apps.
      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 selecting Instrument all when using the MSI install wizard. For more on this, see Set environment variables.
    • If you are changing an existing installation via the MSI install wizard, select the Change option.
    • Use your New Relic license key.
    • Recommended: when prompted by the MSI install wizard, select Instrument all, which sets system-wide environment variables. Optional: you may instead set environment variables on a per-application/process basis:

      Optional: Set environment variables on per-process level

      When using the MSI, you can use Instrument all (or the equivalent AllAppsEnvironmentFeature command line option) to set environment variables system-wide. This allows the New Relic .NET agent to search system-wide for .NET applications that have also been targeted for monitoring. This will work for most use cases. But you can also restrict the agent's initial search to only the .NET processes you choose by setting the required environment variables on a per-process basis.

      When using the 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 placed:

      <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>
      
    • When prompted, give your application a meaningful name.
  5. Define targeted applications using one of the following procedures. For more context on these procedures, see App 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">
    
  6. If using IIS, restart it.

  7. For applications using frameworks not automatically instrumented by New Relic, or for standalone apps (like a console app): you must custom instrument your application to report data.

  8. If an app/process is short-lived (existing for less than 60 seconds), it will not report data and you will need to configure it to report data.

If installed and enabled correctly, data should appear from your application within a few minutes. If not, follow the troubleshooting procedures.

Why defining target applications is necessary

New Relic's .NET Framework agent has two levels of verification that are done before an application can report data to New Relic:

  1. Environment variables must be present: these allow the .NET runtime to attach the New Relic agent to an application.
  2. Next, the applications must be "targeted." This can be done in several ways, including via .NET agent config or application config.

For applications using IIS, the second step is done automatically by default (to override this, see Exclude apps). If you don't use IIS, or if you use IIS via reverse proxy (as you do with an ASP.NET Core app targeting .NET Framework), you must do these steps manually as described in the 'define targeted applications' step of this install procedure.

For more help

Recommendations for learning more: