.NET agent: compatibility and requirements for .NET Core
New Relic's .NET agent supports both .NET Framework and .NET Core. This document describes compatibility and support for .NET Core applications. See Compatibility and requirements for .NET Framework for .NET Framework applications.
New Relic's .NET agent includes built-in instrumentation for some of the most popular parts of the .NET Core 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.
The official product lifecycle start and end dates can be found in the Microsoft documentation. 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 Core 3.1 onwards.
The .NET agent supports .NET Core versions 2.0, 2.1, 2.2, 3.0, 3.1, and .NET 5.0, 6.0, 7.0, and 8.0.
.NET Core version
Minimum required .NET agent version
.NET Core 2.0
8.19.353.0 up to 9.9.0
.NET Core 2.1
8.19.353.0 up to 9.9.0
.NET Core 2.2
8.19.353.0 up to 9.9.0
.NET Core 3.0
8.21.34.0 up to 9.9.0
.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.
The agent is not compatible with .NET Core versions 1.0 or 1.1. For .NET Core 2.1 or higher applications with tiered compilation enabled, the agent will disable tiered compilation. .NET Core 2.1 support requires .NET Core runtime 2.1.3 and .NET Core SDK 2.1.401 or higher due to a bug in the .NET Core profiling API.
The .NET agent only supports applications targeting .NET Core 2.0, 2.1, 2.2, 3.0, 3.1, and .NET 5.0, 6.0, and 7.0. You can find the target framework in your .csproj file. Agent compatibility varies across different versions of .NET Core. For information about which agent version to use for your application's targeted version of .NET Core, please refer to the above section of our documentation, Microsoft .NET Core version.
Supported:
<TargetFramework>netcoreapp2.0</TargetFramework>
<TargetFramework>netcoreapp2.1</TargetFramework>
<TargetFramework>netcoreapp2.2</TargetFramework>
<TargetFramework>netcoreapp3.0</TargetFramework>
<TargetFramework>netcoreapp3.1</TargetFramework>
<TargetFramework>net5.0</TargetFramework>
<TargetFramework>net6.0</TargetFramework>
<TargetFramework>net7.0</TargetFramework>
Important
On Linux ARM64 platforms, the .NET agent only supports target frameworks of net5.0 or higher.
Unsupported:
<TargetFramework>net452</TargetFramework>
Important
If you want to monitor an ASP.NET Core application targeting .NET Framework, ensure your install of the .NET agent has .NET Framework support enabled.
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
The agent has been verified to work with the following operating systems:
Operating system
Supported versions
Windows (32- and 64-bit Intel compatible architectures)
Windows Server 2008 R2 SP1
Windows Server 2012
Windows Server 2012 R2
Windows Server 2016
Windows Server 2019
Windows Server 2022
Windows 10
Windows 11
Windows containers running on Server 2016 (NanoServer based images are not supported)
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:
Alpine Linux
For Azure-specific installation instructions, see:
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.
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 IIS_IUSRS is often used.
The agent requires your firewall to allow outgoing connections to specific networks and ports.
Automatic instrumentation
If your application is hosted in ASP.NET Core, the agent automatically creates and instruments transactions. 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 automatically instruments these application frameworks:
ASP.NET Core MVC 2.0, 2.1, 2.2, 3.0, 3.1, 5.0, 6.0, and 7.0 (includes Web API)
ASP.NET Core Razor Pages 6.0 and 7.0 (starting with .NET agent version 10.19.0)
The .NET agent automatically instruments the performance of .NET application calls to these datastores:
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:
SendAsync
GetAsync
PostAsync
PutAsync
DeleteAsync
GetStringAsync
GetStreamAsync
GetByteArrayAsync
The agent automatically instruments these message systems:
Libraries
Supported methods
Confluent.Kafka
Produce and consume on topics.
The following methods are instrumented:
IProducer.Produce
IProducer.ProduceAsync
IConsumer.Consume
Minimum supported version: 1.4.0
Verified compatible versions: 1.4.0, 2.2.0
NServiceBus
Puts and takes on messages.
Minimum supported version: 5.0
RabbitMQ
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.
BasicGet is instrumented, but the agent does not support distributed tracing for BasicGet.
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.
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 infrastructure hosts by APM app in our infrastructure UI. For more information, see APM data in the infrastructure UI.