.NET agent: compatibility and requirements for .NET Framework
Our .NET agent supports both .NET Framework and .NET Core. Here we describe the compatibility and support for .NET Framework applications. For .NET Core, see Compatibility and requirements for .NET Core.
The agent includes built-in instrumentation for some of the most popular parts of the .NET ecosystem, including frameworks, databases, and message queuing systems. After you download and install the agent, it runs within the monitored process. The agent doesn't create a separate process or service.
Our .NET agent support of these framework versions end with the latest 9.x New Relic .NET agent. Starting from the New Relic .NET agent version 10.0, we will target .NET framework 4.6.2 onwards. For more details, including how you can easily prepare for this transition, see our Support Forum post.
.NET Framework 4.6.2 or higher
.NET Framework 4.6.2 or higher require the New Relic .NET agent version 7.0 or higher.
.NET Framework 4.5.1, 4.5.2, and 4.6.1
To instrument applications running on .NET Framework 4.5.1, 4.5.2, or 4.6.1, you must run a version of the New Relic .NET agent lower than 10.0 but no lower than 7.0.
.NET Framework 4.0 or lower
To instrument applications running on .NET Framework version 4.0 or lower, you must run a version of the New Relic .NET agent lower than 7.0. For more information and download procedures, see Technical support for .NET frameworks 4.0 or lower.
Here are additional details about .NET Framework versions 4.0 or lower:
.NET Framework version
Notes
.NET Framework 2.0
Unless you've 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've installed.
.NET Framework 3.0
Unless you've 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've installed.
.NET Framework 3.5
Fully supported by .NET agent versions lower 7.0.
.NET Framework 4.0
Fully supported by .NET agent versions lower 7.0.
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.
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 lower than 7.0.
The use of Code Access Security is compatible with the .NET agent only when Full Trust is provided. The agent isn't compatible with more restrictive trust levels.
For Azure-specific installation instructions, see:
The agent requires your firewall to allow outgoing connections to specific networks and ports.
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 Server 2022
Windows 10
Windows 11
Windows Azure (OS Family 1, 2, and 3)
Windows containers running on Windows 2016 (NanoServer based images are not supported)
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.
The agent is available in both 32-bit and 64-bit versions. On 64-bit systems, the 64-bit agent can instrument both 32-bit and 64-bit applications.
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.
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 isn't automatically instrumented, or if you want to add instrumentation, use custom instrumentation.
The .NET agent doesn't directly monitor datastore processes. Also, by default the .NET SQL parameter capture in a query trace doesn't 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 (No longer supported in the .NET Agent version 10.0 or higher)
OWIN-hosted web API applications on .NET framework using:
Binding Types (both client and service)
WCF Instrumentation has been tested for the following common binding types. Varying levels of support are available for distributed tracing (DT) and cross application tracing (CAT):
Binding
Distributed Tracing (DT) Support
Cross Application Tracing (CAT) Support
BasicHTTP
supported
supported
WebHTTP
supported
supported
WSHTTP
supported
supported
NetTCP
supported
supported
NetNamedPipe
not supported*
not supported*
NetMSMQ
not supported*
not supported*
* 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 doesn't affect .NET Framework 4.5 or higher.)
Mono: New Relic doesn't 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 New Relic support center.
In order to automatically instrument the performance of .NET Framework application calls to these datastores, make sure you've the .NET agent version 8.14 or higher:
The listed .NET languages and technologies are compatible with our instant observability dashboards. If you use any of these languages or technologies, you can view your data in a New Relic dashboard, right out of the box:
Language/technology
Additional configuration
C# applications
New Relic can automatically instrument services written in C#. Go to our C# quickstart page to install the C# dashboards.
ADO.net
If your application uses ADO.net, you can install a combination of New Relic agents that generate an ADO.net dashboard. Here's what you need to do:
Install the New Relic APM .NET agent and the infrastructure agent by following the steps in our guided installation.
For ASP.NET web 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 Summary page and quickly switch between the APM and browser data for a particular app. For configuration options and manual instrumentation, see Browser monitoring and the .NET agent.
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 hosts by APM app in our infrastructure UI. For more information, see APM data in infrastructure UI.