.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.

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 the New Relic .NET agent on Windows or Linux, make sure your system meets these requirements:

The .NET agent supports .NET Core version 2.0, 2.1, 2.2, 3.0, and 3.1.

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, and 3.1. You can find the target framework in your .csproj file:

Supported:

<TargetFramework>netcoreapp2.0</TargetFramework>
<TargetFramework>netcoreapp2.1</TargetFramework>
<TargetFramework>netcoreapp2.2</TargetFramework>
<TargetFramework>netcoreapp3.0</TargetFramework>
<TargetFramework>netcoreapp3.1</TargetFramework>

Unsupported:

<TargetFramework>net452</TargetFramework>

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

The agent has been verified to work with the following operating systems:

Operating system Supported versions
Windows
  • Server 2008 R2 SP1
  • Server 2012
  • Server 2012 R2
  • Server 2016
  • Server 2019
  • Windows containers running on Server 2016 (NanoServer based images are not supported)
Linux (x64 only)

All x64 Linux distributions supported by .NET Core 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.

Microsoft Azure

For Azure-specific installation instructions, see:

The agent is available in both 32-bit (x86) and 64-bit versions on Windows as well as 64-bit on Linux.

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.

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

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, and 3.1 (includes Web API)

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

Datastore Instance details Notes
Microsoft SQL (MSSQL) Server fa-check Use System.Data.SqlClient version 4.3.1 or Microsoft.Data.SqlClient.
PostgresSQL fa-check

Use Npgsql 4.0.

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

MongoDB fa-check

Use driver version 2.3.x, 2.4.x, 2.5.x, or 2.6.x.

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 Use MySql.Data version 6.10.4.
StackExchange.Redis fa-check

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

Unavailable features

The following features are not available for the .NET agent:

Connect the agent to other New Relic products

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

Product Integration
New Relic Browser

The New Relic Browser JavaScript agent will not be injected by the .NET agent for ASP.NET core applications. However, you can inject the Browser 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 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.

For more help

Recommendations for learning more: