.NET agent: compatibility and requirements for .NET Framework

New Relic's .NET agent supports both .NET Framework and .NET Core. This document describes compatibility and support for .NET Framework applications. See Compatibility and requirements for .NET Core for .NET Core applications.

New Relic's .NET agent includes built-in instrumentation for some of the most popular parts of the .NET Framework ecosystem, including frameworks, databases, and message queuing systems.

After installation, the agent runs within the monitored process; there is not a separate process or service created by the agent.

For frameworks and libraries that are not automatically instrumented out of the box, you can extend the agent with .NET custom instrumentation.

Requirements

Before you install New Relic's .NET agent, make sure your system meets these requirements:

.NET Framework 4.5 or higher

.NET Framework 4.5 or higher requires the New Relic .NET agent version 7.0 or higher.

.NET Framework 4.0 or lower

To instrument applications running on .NET Framework version 4.0 and lower, you must run a version of the New Relic .NET agent earlier than 7.0. For more information and download procedures, see Technical support for .NET frameworks 4.0 or earlier.

Here are additional details about .NET Framework versions 4.0 and lower:

.NET Framework version Notes
.NET Framework 2.0 Unless you have installed only .NET Framework 4.0 or higher, you must have .NET Framework version 3.5 installed on the target host, in addition to any other .NET Framework versions you have installed.
.NET Framework 3.0 Unless you have installed only .NET Framework 4.0 or higher, you must have .NET Framework version 3.5 installed on the target host, in addition to any other .NET Framework versions you have installed.
.NET Framework 3.5 Fully supported by .NET agent versions below 7.0.
.NET Framework 4.0 Fully supported by .NET agent versions below 7.0.

If you use .NET Framework 1.1 for any app on your target system, you must disable instrumentation of that app with applicationPool set to instrument="false". The .NET agent can cause crashes in .NET 1.1 apps.

You must use one of these app/web servers:

  • IIS
  • Self-hosted OWIN
  • Self-hosted WCF
  • Kestrel
  • Kestrel with IIS reverse proxy via AspNetCoreModule
  • Kestrel with IIS reverse proxy via AspNetCoreModuleV2

The agent automatically creates transactions for apps hosted in IIS. If you self-host with WCF and OWIN version 3 or higher, the agent also automatically creates transactions. For other self-hosted services, you will need to create transactions via custom instrumentation.

The agent requires CLR version 4.0. Legacy applications running on CLR 2.0 can be instrumented with agent versions earlier than 7.0.

The agent requires one of these operating systems:

  • Windows Server 2008
  • Windows Server 2008 R2
  • Windows Server 2012
  • Windows Server 2012 R2
  • Windows Server 2016
  • Windows Server 2019
  • Windows 10
  • Windows Azure (OS Family 1, 2, and 3)
  • Windows containers running on Windows 2016 (NanoServer based images are not supported)
Use of other monitoring software

The .NET Common Language Runtime (CLR) only allows one profiler to access the profiling API of a process at any given time. Running our .NET agent alongside other monitoring software will result in a profiler conflict. For more information, see Errors while using other APM software.

Microsoft Azure

For Azure-specific installation instructions, see:

The agent is available in both a 32-bit and 64-bit version. On 64-bit systems, the 64-bit agent can instrument both 32-bit and 64-bit applications.

Installation requires elevated privileges (Administrator). For example, you can:

  • Be logged in as an administrator user.
  • Be a member of the Administrators group.
  • On newer operating systems, provide elevation credentials when prompted.

The monitored process must have read/write access to the directory in which the agent is installed. The agent runs as a part of the monitored process and relies on those permissions to function.

Recommendation:

  • Restrict permissions for the newrelic.config file and give read/write access only to the owner of the monitored process.
  • Review permissions for the logs created by the agent to minimize the number of users with access and their privileges.

As a standard security measure for data collection, your app server must support SHA-2 (256-bit). SHA-1 is not supported.

Network requirements

The agent requires your firewall to allow outgoing connections to specific networks and ports.

Application lifespan

The .NET agent uploads data at the end of each harvest cycle (once per minute). If your .NET app doesn't run that long, you can set the service element's sendDataOnExit attribute to true in the newrelic.config file.

Automatic instrumentation

If your application is hosted in ASP.NET or another fully supported framework, the .NET agent will automatically instrument your application after install. If your app is not automatically instrumented, or if you want to add instrumentation, use custom instrumentation.

The .NET agent does not directly monitor datastore processes. Also, by default the .NET SQL parameter capture in a query trace does not list parameters for a parameterized query or a stored procedure. Collection of the SQL query parameters can be enabled in the agent configuration.

The agent automatically instruments some application frameworks; we refer to these frameworks as fully supported.

Compatibility status .NET app frameworks
Fully supported

These frameworks are fully supported:

  • ASP.NET MVC 2
  • ASP.NET MVC 3
  • ASP.NET MVC 4
  • ASP.NET MVC 5
  • ASP.NET Web API v2
  • ASP.NET Core MVC 2.0
  • ASP.NET Core 2.1
  • ASP.NET Core 2.2
  • ASP.NET Web Forms
  • Castle MonoRail v2 (not the same as Mono)
  • OWIN-hosted web API applications on .NET framework using:
    • Microsoft.Owin.Host.HttpListener v2.x
    • Microsoft.Owin.Host.HttpListener v3.x
    • Microsoft.Owin.Host.HttpListener v4.x
  • SOAP-based web services
  • WCF
    • Hosting Models
      • IIS Hosted (with and without ASP Compatibility)
      • Self Hosted
    • Binding Types (both client and service)
      • HTTP Based Binding Types
        These bindings are instrumented and automatically support Distributed Tracing (DT) and Cross Application Tracing (CAT).
        • Common bindings include:
          • Basic HTTP
          • WSHTTP
          • WebHTTP
      • Non-HTTP Based Binding Types
        These bindings are instrumented, but do not automatically support Distributed Tracing (DT) and Cross Application Tracing (CAT).
        • Common bindings include:
          • NetTCP
          • NetNamedPipe
          • NetMSMQ
        • Distributed Tracing may be manually implemented using these Distributed Tracing API methods.
           
    • Invocation Methods (both client and service)
      • Synchronous
      • Asynchronous Processing Model (APM) Begin/End
      • Task Asynchronous Processing (TAP)
      • Event-based Asynchronous Processing (EAP)
        • Client support only.
Not fully supported

These frameworks are not fully supported:

  • ASP.NET Web API v1: See the troubleshooting information about using ASP.NET Web API v1 with New Relic's .NET agent 5.0 or higher for apps targeting .NET Framework 4.0. (This does not affect .NET Framework 4.5 or higher.)
  • Mono: New Relic does not support Mono, an open-source .NET framework that runs on Linux. This is because there is no Profiler API to inject into the .NET agent as a profiler into Mono-based .NET applications. The Profiler API is a Component Object Model (COM)-based interface and is not supported on Linux.
Not supported

Classic ASP is not supported, because the agent can only instrument .NET Framework-based apps.

Sharepoint is not supported.

Collecting instance details for supported datastores requires .NET agent version 6.5.29.0 or higher and is enabled by default. To request instance-level information from datastores not currently listed, get support at support.newrelic.com.

In order to automatically instrument the performance of .NET Framework application calls to these datastores, make sure you have the .NET agent version 8.14 or higher:

Datastore Instance details Other notes
Couchbase

SDK version 2.0 or higher.

With Couchbase, the following are not instrumented by default in favor of their multi-document counterparts:

  • Get(string key)
  • GetDocument(string key)
  • Remove(string key)
  • Remove(string key, ulong cas)
  • Upsert<T>(string key, T value)
IBM DB2 fa-check
Microsoft SQL Server fa-check
MongoDB fa-check

Driver version 2.3.x, 2.4.x, 2.5.x, or 2.6.x

Driver versions 1.10.0 or earlier: Instance details are not available in these driver versions.

Driver version 2.7.x: The .NET agent will support pre-existing API methods, but not new methods introduced in 2.7.x.

MySQL fa-check
Oracle fa-check
PostgreSQL fa-check

Use Npgsql 4.0.

Prior versions of Npgsql may also be instrumented, but duplicate and/or missing metrics are possible.

ServiceStack.Redis fa-check
StackExchange.Redis fa-check

The agent automatically instruments these message systems:

  • MSMQ: Puts and takes on messages
  • NServiceBus 5.0 (6.0 or higher not supported): Puts and takes on messages and cross application tracing
  • RabbitMQ 3.5 or higher: Puts and takes on messages and queue purge. When receiving messages using an IBasicConsumer, the EventingBasicConsumer is the only implementation that is instrumented by the .NET agent.

The agent automatically instruments the EPiServer content management system.

The agent automatically instruments these external call libraries :

Libraries Supported methods
HttpClient

The agent instruments these HttpClient methods:

  • SendAsync
  • GetAsync
  • PostAsync
  • PutAsync
  • DeleteAsync
  • GetStringAsync
  • GetStreamAsync
  • GetByteArrayAsync
RestSharp

The agent instruments these RestSharp methods:

  • ExecuteTaskAsync
  • ExecuteGetTaskAsync
  • ExecutePostTaskAsync
  • Execute
  • ExecuteAsGet
  • ExecuteAsPost
  • DownloadData
HttpWebRequest

The agent instruments these HttpWebRequest methods:

  • GetResponse

Connect the agent to other New Relic products

In addition to New Relic APM, the agent integrates with other New Relic products to give you end-to-end visibility:

Product Integration
New Relic Browser

For ASP.NET applications, the .NET agent automatically injects the Browser JavaScript agent when you enable auto-instrumentation. After enabling Browser injection, you can view Browser data in the APM Overview page and quickly switch between the APM and Browser data for a particular app. For configuration options and manual instrumentation, see New Relic Browser and the .NET agent.

Automatic Browser injection is not supported for ASP.NET core applications.

New Relic Infrastructure When you install the Infrastructure and APM agents on the same host, they automatically detect one another. You can then view a list of hosts in the APM UI, and filter your Infrastructure hosts by APM app in the Infrastructure UI. For more information, see New Relic APM data in Infrastructure.
New Relic Insights The .NET agent sends default events and attributes to Insights for NRQL queries. You can also record custom events for advanced analysis.
New Relic Synthetics Synthetic transaction traces connect requests from Synthetics monitors to the underlying APM transaction.

For more help

Recommendations for learning more: