New Relic .NET Agent Setup and Requirements

To set up the New Relic .NET agent, you'll need to install the agent on your .NET application. The agent is compatible with .NET Framework 4.6.1 and later versions, as well as .NET Core 2.1 and later versions.

The .NET agent requires the .NET Framework 4.6.1 or later, or .NET Core 2.1 or later to be installed on your system. The agent also requires the Microsoft Visual C++ Redistributable package to be installed.

You can install the .NET agent using the NuGet package manager or by downloading the agent from the New Relic website. Once installed, you'll need to configure the agent to collect data from your application.

The .NET agent supports various configuration options, including the ability to collect data from multiple .NET applications and to exclude certain assemblies from collection. You can configure the agent using the New Relic .NET agent configuration file or by using the New Relic .NET agent API.

You can instrument your .NET application using various methods, including auto-instrumentation, manual instrumentation, and custom instrumentation. Auto-instrumentation is supported for ASP.NET Core applications running on Kestrel, while manual instrumentation can be achieved via the New Relic .NET agent API.

To enable auto-instrumentation, ensure your .NET agent version is 8.14 or higher, and that you're using a supported framework such as ASP.NET Core MVC or Razor Pages. If your app uses a non-supported framework, you'll need to manually instrument it using the RecordDatastoreSegment method in the .NET agent API.

Manual instrumentation can be done via two methods: manual instrumentation via agent API and manual instrumentation with copy/paste. The first method involves using the New Relic .NET agent API and including appropriate code in your pages, while the second method involves manually inserting the JavaScript snippet into your app's webpages.

Here are the details of the supported frameworks for auto-instrumentation:

This list includes some of the many supported frameworks for auto-instrumentation, and you can find the full list in the compatibility documentation.

You can use the .NET agent API to manually instrument your application. This is useful when you need to add instrumentation to a specific view or page where auto-instrumentation is not needed.

To disable auto-instrumentation on a particular view, use the agent API call DisableBrowserMonitoring(). Add this call as close to the top of the view as possible.

To disable both auto-instrumentation and manual instrumentation for individual webpages, use the agent API call DisableBrowserMonitoring(true).

If your application isn't automatically instrumented, or if you want to add instrumentation, use custom instrumentation.

Custom instrumentation can be added using the RecordDatastoreSegment method in the .NET agent API.

The .NET agent automatically instruments certain external call libraries, including HttpClient. The agent instruments these HttpClient methods:

* SendAsyncSendAsyncSendAsync

You can use the NewRelic.Agent.Api support to add custom instrumentation to your application.

For a more detailed list of supported libraries and frameworks, see the compatibility documentation.

The .NET download library is a crucial part of the New Relic .NET agent installation process. It contains install file packages that are referenced in specific install procedures.

These packages can be found in the download library's ReadMe file, which provides more information on the files included.

You can control instrumentation in the New Relic .NET agent to suit your needs. To fully disable auto-instrumentation, edit the newrelic.config file and set the browserMonitoringautoInstrument flag to false.

You can also use the agent API call DisableBrowserMonitoring() to disable auto-instrumentation on a particular view. This call should be added as close to the top of the view as possible.

Disabling auto-instrumentation for a specific view is especially useful when you don't need or want browser scripts in certain situations.

Here are some ways to control instrumentation in the New Relic .NET agent:

To fully disable auto-instrumentation, you'll need to edit your newrelic.config file and set the browserMonitoringAutoInstrument flag to false. This will prevent New Relic from automatically collecting data from your application.

Make sure to flush your cache after making this change, as this will remove references to the agent from compiled files. This ensures that the changes take effect correctly.

If you only want to disable auto-instrumentation for a specific view, you can use the DisableBrowserMonitoring() API call. This call should be placed as close to the top of the view as possible.

You can also use the DisableBrowserMonitoring(true) API call to disable both auto-instrumentation and manual instrumentation for individual webpages.

To enable browser auto-instrumentation for .NET Core v6+ web applications, you'll need to meet certain requirements. You'll need the .NET agent v10.19.2 or later.

First, ensure you've enabled auto-instrumentation globally by editing the newrelic.config file and setting the browserMonitoringautoInstrument flag to true. This is a crucial step.

Next, add a new item in the appSettings section of the newrelic.config file, or create this section if it doesn't exist. You'll need to add a key named "EnableAspNetCore6PlusBrowserInjection" with a value of "true".

Here are the specific steps to enable auto-instrumentation for .NET Core 6+ web apps:

Remember to thoroughly test this feature in a non-production environment to ensure compatibility with your web application. If you experience any issues, don't hesitate to contact the support team for assistance.

You have two options for installing the New Relic .NET Agent. You can either download the ZIP file from the .NET agent download site or get the latest released binaries from either the New Relic site or NuGet.org.

To manually install the agent using a ZIP file, you'll need to choose the correct file for your application's architecture, either 64-bit or 32-bit. The ZIP file should be unzipped in the desired location, and then environment variables need to be set for the process you wish to monitor.

Here are the environment variables required for the .NET Framework: VariableValueCOR_ENABLE_PROFILING1COR_PROFILER{71DA0A04-7777-4EC6-9643-7D28B46A8A41}NEWRELIC_HOMEpath\to\agent\directory

etframeworkCOR_PROFILER_PATHpath\to\agent\directory

etframework\NewRelic.Profiler.dll

For .NET Core/.NET 5+, the environment variables required are slightly different: VariableValueCORECLR_ENABLE_PROFILING1CORECLR_PROFILER{36032161-FFC0-4B61-B559-F6C5D41BAE5A}CORECLR_NEWRELIC_HOMEpath\to\agent\directory

etcoreCORECLR_PROFILER_PATHpath\to\agent\directory

etcore\NewRelic.Profiler.dll

If you want to manually install the .NET agent using a ZIP file, you'll need to download the correct file for your application's architecture, either 64-bit or 32-bit.

To get started, head to the .NET agent download site and grab the right file for your needs. You can then unzip the agent folder in the desired location.

Setting environment variables is a crucial step in the manual install process. For .NET Framework, you'll need to set the following variables: COR_ENABLE_PROFILING=1, COR_PROFILER={71DA0A04-7777-4EC6-9643-7D28B46A8A41}, NEWRELIC_HOME=path\to\agent\directory

etframework, and COR_PROFILER_PATH=path\to\agent\directory

etframework\NewRelic.Profiler.dll.

For .NET Core/.NET 5+, you'll need to set the following variables: CORECLR_ENABLE_PROFILING=1, CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}, CORECLR_NEWRELIC_HOME=path\to\agent\directory

etcore, and CORECLR_PROFILER_PATH=path\to\agent\directory

etcore\NewRelic.Profiler.dll.

Remember to copy these variables, as they need to be set for the process you wish to monitor. Don't set them globally, as this can cause issues with other .NET processes on the system.

Once you've set the environment variables, restart your application and IIS if you're using it. This will ensure the changes take effect and the .NET agent is properly installed.

Scriptable Windows Installers are ZIP archives containing a PowerShell script for installing the .NET agent. There is a separate zip archive for .NET Framework versus .NET Core.

We recommend using the MSI installer over the scriptable installer, but if you want to automate your install, consider running the MSI installer from the command line. As of .NET agent version 10.0.0, the scriptable installers are no longer available, but this documentation remains for customers who wish to use the scriptable installer for an older version.

To use the scriptable installer to install the .NET agent for a .NET Framework app, you'll need to download the scriptable installer package from the download site and accept the license terms. Ensure you have administrator rights for your Windows admin group, and you can find more details on this in the permissions documentation.

You'll need to unzip the package, open a command shell, and navigate into the unzipped package's folder. To install with no options, use the command `.\install.cmd -LicenseKey YOUR_LICENSE_KEY`. If you want to install with one or more additional options, use the format below:

To uninstall the agent with the scriptable uninstaller, you can add the Force option to the uninstall script to force an uninstall without prompting to restart IIS. Execute the command `.\uninstall.cmd` to uninstall the .NET agent.

The New Relic .NET agent is a powerful tool for monitoring and optimizing your .NET applications. You can install it manually using a ZIP file or through NuGet.org.

To manually install the agent, you'll need to download the correct file for your application's architecture, either 64-bit or 32-bit. This will ensure that the agent is compatible with your system.

The agent is compatible with .NET Core version 3.1, and .NET 5.0, 6.0, 7.0, 8.0, and 9.0, so make sure your system meets these requirements before installation.

Here are the environment variables you'll need to set for the .NET Framework:

etframeworkCOR_PROFILER_PATH=path\to\agent\directory

etframework\NewRelic.Profiler.dll

For .NET Core/.NET 5+, you'll need to set the following environment variables:

etcoreCORECLR_PROFILER_PATH=path\to\agent\directory

etcore\NewRelic.Profiler.dll

To install the .NET agent, you can download the latest released binaries from either the official website or NuGet.org. This will give you access to the necessary files for your application type and hosting environment.

The .NET agent download site offers two types of files: 64-bit and 32-bit. You'll need to choose the correct file that matches your application's architecture.

You can manually install the agent using a ZIP file. This involves unzipping the agent folder in the desired location and setting environment variables for the process you wish to monitor.

Here are the environment variables required for .NET Framework:

etframeworkCOR_PROFILER_PATH=path\to\agent\directory

etframework\NewRelic.Profiler.dll

And here are the environment variables required for .NET Core/.NET 5+:

etcoreCORECLR_PROFILER_PATH=path\to\agent\directory

etcore\NewRelic.Profiler.dll

After setting the environment variables, you'll need to restart your application, and if using IIS, restart IIS as well.

The .NET agent is compatible with .NET Core version 3.1, and .NET 5.0, 6.0, 7.0, 8.0, and 9.0.

To ensure a smooth installation process, make sure your system meets the necessary requirements. The agent has been verified to work with Windows and Linux operating systems.

Before installing the .NET agent, ensure you have the required permissions to do so. Installing and running the .NET agent requires these permissions.

The following hosting models are fully supported:

When executing the installAgent.ps1 script, it's essential to prepend ./ to the script filename rather than powershell. This is because prepending powershell can corrupt arguments with spaces, leading to an insecure installation.

Ensure you have administrator rights for your Windows admin group, as this is required for the installation process. For more details on this, see the permissions documentation.

To avoid any issues, make sure to download the .NET agent's scriptable installer package from the .NET agent download site and unzip it in the desired location.

Here are the install options you can use with the installAgent.ps1 script: