Update the .NET agent

How to update the New Relic APM .NET agent.

Check your .NET agent version

  1. Refer to the release notes to find the latest version of the agent.
  2. Check the version of the .NET agent you currently have installed by using Windows Programs and Features or by using your Linux package manager.

  3. Follow the update instructions for your agent:

Update the .NET Framework agent

Before updating:

  • Note: Updating the agent requires Administrator rights in your Windows admin group. For more information, see the permissions documentation.
  • If your .NET Framework agent version is lower than 7.0 or you are using .NET Framework version 4.0 or lower, see Update legacy .NET agent.
Standard install
  1. Ensure that you have .NET 4.5 or higher installed on your system.
  2. Stop IIS.
  3. Download and run the appropriate MSI install package for your architecture:

  4. After the installer package finishes, start IIS.
Scriptable installer

You can update the .NET Framework agent on Windows using a scriptable installer.

Update the .NET Core agent

Updating the agent requires Administrator rights in your Windows admin group. For more information, see the permissions documentation.

Use one of the following methods to update to the latest version of New Relic's .NET Core agent:

zip, tar.gz, deb file
  1. Shut down your application(s).
  2. Download and run the appropriate install file for your architecture from the download site.

  3. Extract the downloaded zip file on top of the existing files.
  4. Restart your application(s).
yum (CentOS, Oracle Linux, or RHEL)
  1. Shut down your application(s).
  2. Use the following to update the agent:
    sudo yum update newrelic-netcore20-agent
apt (Debian, Linux Mint, or Ubuntu)
  1. Shut down your application(s).
  2. Use the following to get a list of available updates and install them:
    sudo apt-get update && sudo apt-get install --only-upgrade newrelic-netcore20-agent
rpm (CentOS, Oracle Linux, or RHEL)
  1. Shut down your application(s).
  2. Download and run the appropriate rpm file for your architecture from the download site.

  3. Use the following to update the agent:
    sudo rpm -Uvh FILE_NAME.rpm
Scriptable installer
You can update the .NET Core agent on Windows using a scriptable installer.

Update older .NET Framework agents (lower than 7.0)

If you are considering updating a .NET Framework agent version that is lower than 7.0, review the following notes. To see the agent version you have, see Check agent version. For a full list of agent changes, see the .NET release notes.

.NET Framework legacy agent version details

To instrument applications targeting .NET Framework 4.0 or earlier, you must use a version of the .NET Framework agent prior to 7.0. See support for .NET Frameworks 4.0 or earlier for more information.

If version is lower than... Do this...
7.0

Version 7.0 and higher of the .NET Framework agent support applications that target .NET Framework 4.5 or higher.

6.12

Versions 6.12 or higher do not support Windows Server 2003. If you require Windows Server 2003, use versions 6.11 or lower. For more information, get support at support.newrelic.com or download the agent at http://download.newrelic.com/

6.11

Previously, database and external calls that occurred outside of a transaction would generate metrics that you could view in their respective pages in the New Relic APM UI. Now these metrics will not be displayed. In a non-web application these calls can be "wrapped" in a custom transaction to be able to view their metrics.

6.0

To get async support if your .NET agent version is earlier than 6.0, do the following as applicable:

  1. Remove the following application setting in newrelic.config if it exists:

    <appSettings>
      <add key="AsyncMode" value="false" />
    </appSettings>
  2. Ensure your app's host has .NET 4.5 or higher installed.
  3. Tell .NET to use the new ASP request processing pipeline by adding the following lines to your web.config:

    <configuration>
      <appSettings>
        <add key="aspnet:UseTaskFriendlySynchronizationContext" value="true" />
      </appSettings>
    <configuration>
    

    OR

    Specify the .NET Framework version to be 4.5.2 or higher by adding the following lines to the web.config:

    <configuration>
      <system.web>
        <httpRuntime targetFramework="YOUR_TARGET_NET_VERSION" /> 
      </system.web>
    <configuration>
    

5.0 (for Web API)

To see Web API transactions, you must opt in to a .NET framework bug fix if the following conditions apply:

  • You use ASP.NET Web API v1.
  • Your app targets .NET Framework agent version 4.0. (This issue does not affect version 4.5 or higher.)
  • You are upgrading from .NET Framework agent to version 5.0 or higher.

To apply the fix:

  1. Ensure your app's host has .NET 4.5 installed.
  2. Add this appSetting to your web.config:

    <configuration>
      <appSettings>
        <add key="aspnet:UseTaskFriendlySynchronizationContext" value="true" />
      </appSettings>
    <configuration>
    

For more information about this .NET framework bug, see Why is HttpContext.Current null after await? and All about <httpRuntime targetFramework>.

5.0 (for metrics)

Metrics that are not part of a transaction will not be displayed in the UI. Exception: You can view database and external metrics in their respective pages in the New Relic APM UI. Other such metrics (such as instrumented methods) can be made viewable by "wrapping" them in a custom transaction.

Your custom instrumentation may need to be updated to use custom transactions. For an example of what you will see in the UI, see this New Relic Online Technical Community post.

4.4

New Relic improved transaction naming. However, these changes can affect the transaction names of existing metrics, including key transactions, "alert on anything" metrics, and Insights queries based on transaction names. You must recreate these settings using the new transaction name after the upgrade.

4.2

New Relic dropped the "outer" HTTP transaction (".svc" transactions) for WCF applications hosted with asp.net compatibility mode disabled. Now only the WCF transaction is reported.

This change results in more accurate throughput data. It also prevents HTTP status code errors from being reported for failed WCF transactions.

4.1

New Relic implemented datastore metrics for SQL traces. Metric names for database activity were updated to report under datastore.

4.0

MVC2 applications no longer generate MVC-specific segments or have MVC route-based transaction names.

3.0

New Relic's .NET agent became dependent on .NET 3.5. Your application can still target .NET 2.0, but you must have .NET 3.5 installed on the computer on which the agent executes.

2.20

Version 2.19.3.0 was the last .NET agent version that required both the GetBrowserTimingFooter() and the GetBrowserTimingHeader() API calls for browser monitoring. In agent version 2.20.24.0 or higher, you only need to call GetBrowserTimingHeader(). GetBrowserTimingFooter() has no effect. Recommendation: Remove these references from your code.

2.9

The configuration file changed from newrelic.xml to newrelic.config. Installers for newer agents attempt to convert newrelic.xml (if present) to newrelic.config.

2.8

(established .NET Framework release)

This version is designated as the established .NET Framework agent release. For more information, see the .NET agent 2.8.134.1 release notes.

2.2 or earlier

To upgrade from a .NET agent version earlier than 2.2, you must uninstall the old agent before installing the new version. Follow the standard procedures for your Windows version to uninstall the agent. Your operating system may require a restart.

You may experience cocreateinstance errors with services.exe when you upgrade an old installer (2.1.3.494 or earlier) or make other changes to environment variables. To resolve this problem, refer to Microsoft's documentation.

For more help

Recommendations for learning more: