Requirements
Before you install the New Relic .NET agent on Windows or Linux, make sure your system meets these requirements:
The .NET agent supports .NET Core version 3.1, and .NET 5.0, 6.0, and 8.0.
.NET Core version | Minimum required .NET agent version |
|---|---|
.NET Core 3.1 | 8.21.34.0 and higher |
.NET 5.0 | 8.35.0 and higher |
.NET 6.0 | 9.2.0 and higher |
.NET 7.0 | 10.0.0 and higher |
.NET 8.0 | 10.0.0 and higher |
Important
On Linux ARM64 platforms, the .NET agent only supports versions of .NET 5.0 or higher.
Ensure you use one of these app/web servers:
- Kestrel
- Kestrel with IIS reverse proxy via AspNetCoreModule
- Kestrel with IIS reverse proxy via AspNetCoreModuleV2
- Kestrel with Nginx reverse proxy
- Kestrel with Apache reverse proxy
- In-process hosting
For AWS Elastic Beanstalk installation instructions, see the .NET installation guide.
For Azure-specific installation instructions, see the .NET installation guide.
The agent requires your firewall to allow outgoing connections to specific networks and ports.
The agent has been verified to work with the following operating systems:
Operating system | Supported versions |
|---|---|
Windows (32- and 64-bit Intel compatible architectures) |
|
Linux (64-bit Intel compatible only) | All x64 Linux distributions supported by the .NET Core 2.0+/.NET 5+ runtime are supported by the .NET agent. For a full list, refer to Microsoft's documentation for the version of the runtime you are using. |
Linux (ARM64/aarch64 architectures) | All ARM64 Linux distributions supported by the .NET 5+ runtime are supported by the .NET agent, with the following known exceptions:
|
Installing and running the .NET agent requires these permissions:
Component | Necessary permissions |
|---|---|
Install the agent | The process or user that installs the agent must have sufficient permissions to set environment variables and write access to the directory where the agent is installed. |
Run the agent | The monitored process must have read/write access to the directory in which you installed the agent. The agent runs as a part of the monitored process and relies on those permissions to function. For applications using IIS via reverse proxy, the group |
The agent is available in both 32-bit (x86) and 64-bit (x64) versions on Windows as well as both 64-bit (x64) and ARM64 (aarch64) versions on Linux.
Important
On Linux ARM64 platforms, the .NET agent only supports versions of .NET 5.0 or higher.
As a standard security measure for data collection, your app server must support SHA-2 (256-bit). SHA-1 is not supported.
The .NET agent only supports applications targeting .NET Core 3.1, and .NET 5.0, 6.0, and 8.0. You can find the target framework in your .csproj file. Agent compatibility varies across different versions of .NET Core.
Supported:
<TargetFramework>netcoreapp3.1</TargetFramework>
<TargetFramework>net5.0</TargetFramework>
<TargetFramework>net6.0</TargetFramework>
<TargetFramework>net7.0</TargetFramework>
<TargetFramework>net8.0</TargetFramework>
Important
On Linux ARM64 platforms, the .NET agent only supports target frameworks of net5.0 or higher.
Unsupported:
<TargetFramework>net452</TargetFramework>
If you want to monitor an ASP.NET Core application targeting .NET Framework, ensure that you have enabled the .NET Framework support after installing the .NET agent.
Automatic instrumentation
If your application is hosted in ASP.NET Core, the agent automatically creates and instruments transactions. The .NET agent automatically instruments your application after install. If your app is not automatically instrumented, or if you want to add instrumentation, use custom instrumentation.
The .NET agent automatically instruments these application frameworks:
- ASP.NET Core MVC 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, 7.0, and 8.0 (includes Web API)
- ASP.NET Core Razor Pages 6.0, 7.0, and 8.0 (starting with .NET agent version 10.19.0)
The .NET agent automatically instruments the performance of .NET application calls to these datastores:
Datastore | Instance details | Notes |
|---|---|---|
Cosmos DB | The .NET agent
| |
Microsoft SQL Server | Use SqlClient from System.Data.SqlClient NuGet package or Microsoft.Data.SqlClient NuGet package. System.Data.SqlClient
| |
PostgreSQL | Use Npgsql
| |
MongoDB (modern driver) | Minimum supported version: 2.3.0 Latest verified compatible version: 2.26.0 Beginning in agent version 10.12.0, the following methods added in or after driver version 2.7 are instrumented:
| |
MySQL | Use MySql.Data or MySQL Connector MySql.Data
| |
StackExchange.Redis | Minimum supported version: .0.488 Latest verified compatible version: 2.7.33 | |
Elasticsearch | Use Elastic.Clients.Elasticsearch, NEST, or Elasticsearch.Net. Elastic.Clients.Elasticsearch
|
The .NET 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.
Collecting instance details for supported datastores is enabled by default. To request instance-level information from datastores not currently listed, get support at support.newrelic.com.
The .NET agent automatically instruments these external call libraries :
Libraries | Supported methods |
|---|---|
HttpClient | The agent instruments these HttpClient methods:
|
The .NET agent can be configured to automatically instrument these LLM frameworks:
Frameworks | Minimium framework version | Minimium agent version | Latest verified compatible version |
|---|---|---|---|
AWS Bedrock | 3.7.200.0 | 10.23.0 | 3.7.301.45 |
The .NET agent can be configured to automatically instrument these logging frameworks for automatic logs-in-context with agent forwarding and local log decoration:
Frameworks | Minimium framework version | Minimium agent version | Latest verified compatible version |
|---|---|---|---|
Log4Net | 2.0.10 | 9.7.0 | 2.0.16 |
Serilog | 2.5.0 | 9.7.0 | 3.1.1 |
NLog | 4.5.0 | 9.7.0 | 5.3.2 |
Microsoft.Extensions.Logging | 3.0.0 | 10.0.0 | 8.0.0 |
The agent automatically instruments these message systems:
Libraries | Supported methods |
|---|---|
Confluent.Kafka |
|
NServiceBus |
|
RabbitMQ |
|
MassTransit (agent versions 10.19.0 and newer) |
|
Unavailable features
The following features are not available for the .NET agent:
The .NET agent does not support trim self-contained deployments and executables, because the compiler can potentially trim assemblies that the agent depends on.
Infinite Tracing is not supported on Alpine Linux due to a GRPC compatibility issue. See this agent issue for more information.
The .NET agent doesn't support Native Ahead of Time (AOT) deployment for .NET applications because just-in-time (JIT) compilation is required for the agent to function properly.
Connect the agent to other New Relic products
In addition to APM, the .NET agent integrates with other New Relic products to give you end-to-end visibility:
Product
Integration
Browser monitoring
For ASP.NET Core v6.0 and later web applications (MVC, Razor and Blazor), the .NET agent (starting with version 10.19.0) automatically injects the browser JavaScript agent when you enable auto-instrumentation.
For other types of web applications, you can inject the agent by using the .NET agent API or the browser agent's copy/paste method.
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.
Infrastructure monitoring
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 our infrastructure UI. For more information, see APM data in the infrastructure UI.
Dashboards
The .NET agent sends default events and attributes for NRQL queries. You can also record custom events for advanced analysis.
Requirements
Before you install New Relic's .NET agent, make sure your system meets these requirements:
.NET Framework 4.6.2 or higher
To instrument applications running on .NET Framework 4.6.2 or higher, you must run the New Relic .NET agent 10.0 or higher. 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.
The .NET agent doesn't support .NET Framework versions 4.5.1, 4.5.2, and 4.6.1
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.
AWS Elastic Beanstalk isn't a supported .NET environment.
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 .NET installation guide.
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.configfile 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.
As a standard security measure for data collection, your app server must support SHA-2 (256-bit). SHA-1 isn't supported.
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, which are listed below:
- 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:
- Microsoft.Owin.Host.HttpListener v2.x
- Microsoft.Owin.Host.HttpListener v3.x
- Microsoft.Owin.Host.HttpListener v4.x
- SOAP-based web services
- WCF
WCF Instrumentation has been tested for the following commonbinding types (both client and service). 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 (Deprecated) |
|---|---|---|
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.
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:
Datastore | Instance details | Other notes |
|---|---|---|
Cosmos DB | The .NET agent
| |
Couchbase | Use CouchbaseNetClient.
| |
IBM DB2 | ||
Microsoft SQL Server | Use SqlClient from System.Data.SqlClient NuGet package or Microsoft.Data.SqlClient NuGet package or the Framework built-in System.Data assembly. System.Data.SqlClient
| |
MongoDB (legacy driver) | Minimum supported version: 1.10.0 Latest verified compatible version: 1.10.0 Known incompatible versions: Instance details aren't available in lower version 2. | |
MongoDB (modern driver) | Minimum supported version: 2.3.0 Latest verified compatible version: 2.26.0 Beginning in agent version 10.12.0, the following methods added in or after driver version 2.7 are instrumented:
| |
MySQL | Use MySql.Data or MySQL Connector MySql.Data
| |
Oracle | ||
PostgreSQL | Use Npgsql
| |
ServiceStack.Redis | ||
StackExchange.Redis |
| |
Elasticsearch | Use Elastic.Clients.Elasticsearch, NEST, or Elasticsearch.Net. Elastic.Clients.Elasticsearch
Elasticsearch.Net
|
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:
|
RestSharp | The agent instruments these RestSharp methods:
|
HttpWebRequest | The agent instruments these HttpWebRequest methods:
|
The following hosting models are fully supported:
- IIS Hosted (with and without ASP Compatibility)
- Self Hosted
The following invocation methods (both client and service) are supported:
- Synchronous
- Asynchronous Processing Model (APM) Begin/End
- Task Asynchronous Processing (TAP)
- Event-based Asynchronous Processing (EAP, client support only)
The .NET agent can be configured to automatically instrument these LLM frameworks:
Frameworks | Minimium framework version | Minimium agent version | Latest verified compatible version |
|---|---|---|---|
AWS Bedrock | 3.7.200.0 | 10.23.0 | 3.7.301.45 |
The .NET agent can be configured to automatically instrument these logging frameworks for automatic logs-in-context with agent forwarding and local log decoration:
Frameworks | Minimium framework version | Minimium agent version | Latest verified compatible version |
|---|---|---|---|
Log4Net | 1.2.10 | 9.7.0 | 2.0.16 |
Serilog | 2.0.0 | 9.7.0 | 3.1.1 |
NLog | 4.1.0 | 9.7.0 | 5.3.2 |
Microsoft.Extensions.Logging | 3.0.0 | 9.7.0 |
The agent automatically instruments these message systems:
Libraries | Supported methods |
|---|---|
Confluent.Kafka |
|
MSMQ |
|
NServiceBus |
|
RabbitMQ |
|
MassTransit (agent versions 10.19.0 and newer) |
|
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:
|
Blazor Server | Track your most important data in our Blazor Server dashboard by instrumenting your app with New Relic:
|
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.
- Classic ASP is not supported, because the agent can only instrument .NET Framework-based apps.
- Sharepoint is not supported.
Unavailable features
Just-in-time (JIT) compilation is a requirement for .NET agent functionality, so native images created with Native Image Generator (NGEN) aren't supported by the .NET agent.
Connect the agent to other New Relic products
In addition to APM, the agent integrates with other New Relic products to give you end-to-end visibility:
Product | Integration |
|---|---|
Browser monitoring | 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 and data for a particular app. For configuration options and manual instrumentation, see Browser monitoring and the .NET agent. |
Infrastructure monitoring | 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. |
Dashboards | The .NET agent sends default events and attributes for NRQL queries. You can also record custom events for advanced analysis. |
Synthetic monitoring | Synthetic transaction traces connect requests from synthetic monitors to the underlying APM transaction. |
