Compatibility and requirements for the .NET Framework agent

New Relic's .NET Framework agent includes built-in instrumentation for the most popular parts of the .NET Framework ecosystem. The agent runs within the monitored process; there is no separate process or Windows service associated with the agent. The .NET Framework agent supports a variety of .NET frameworks, operating systems, and app frameworks. For installation instructions, see Install the .NET agent on Windows.

The .NET Core 2.0 agent includes functionality of the .NET Framework agent. However, if you want to take advantage of the compatibility, speed, expanded API features, and cross-platform capabilities available as of Microsoft's .NET Core version 2.0, use the .NET Core 2.0 version of the agent. It also allows you to monitor Kestrel apps on both Linux and Windows. For more information, see the compatibility and requirements for New Relic's .NET Core 2.0 agent.

Requirements

Before you install the New Relic for .NET Framework agent, make sure your system meets these requirements:

Agent version 7.0 and higher

New Relic .NET agent version 7.0 and higher requires being run on .NET Framework 4.5 and higher.

Agent versions lower than 7.0

Instrumenting applications running on .NET Framework version 4.0 and below require you to run a version of the New Relic .NET agent lower than 7.0. See Technical support for .NET frameworks 4.0 or earlier for more information and download instructions.

The .NET agent versions lower than 7.0 requires one of these .NET Framework versions:

Supported 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
.NET Framework 4.0
.NET Framework 4.5
.NET Framework 4.6

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

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 versions of the agent prior to 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 10
  • Windows Azure (OS Family 1, 2, and 3)

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.

The installer requires elevated privileges (Administrator) to install. You can be logged in as an administrator user, be a member of the Administrators group, or (on newer operating systems) provide elevation credentials when prompted.

New Relic recommends you restrict permissions for the newrelic.config file to give read/write access only to the owner of the app server process. Also, review the 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.

Instrumented features

If your app is hosted in ASP.NET, the agent usually automatically creates and instruments transactions. The list of instrumented features below are features that New Relic has specifically tested with the .NET Framework agent, or for which the agent collects additional detail. You can also extend your instrumentation with custom instrumentation and the agent API.

The .NET Framework agent does not directly monitor datastore processes. Also, the .NET SQL parameter capture in a query trace does not list parameters for a parameterized query or a stored procedure.

The agent includes default instrumentation for these frameworks and features:

Collecting instance details for supported datastores requires .NET Framework 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.

The agent automatically instruments the performance of .NET Framework application calls to these datstores:

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 versions 1.10.0 or earlier
MySQL fa-check
Oracle fa-check
PostgreSQL fa-check Via Npgsql .NET Data Provider
ServiceStack.Redis fa-check
StackExchange.Redis fa-check

The agent automatically instruments these application frameworks:

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 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
  • SOAP-based web services
  • WCF apps, whether hosted in IIS or self-hosted
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 Framework agent 5.0 or higher for apps targeting .NET Framework 4.0. (This does not affect .NET Framework 4.5 or higher.)
  • Mono: Currently 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 Framework 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.

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 these content management systems:

  • EPiServer
  • Umbraco (version 6.1.6 or higher)

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
RestClient

The agent instruments these RestClient 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 The .NET Framework 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.
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: