Refer to the release notes to find the latest version of the agent.
Check the version of the .NET agent you currently have installed by using Windows Programs and Features or by using your Linux package manager.
Before you start
There are several ways you can install the .NET agent, which means there are several ways to update it. In this doc, we focus on the update procedures for the simplest installations, with the .NET agent installed directly on a Windows or Linux host.
If you have other installations, see these install docs for those setups for more context:
For .NET agent versions 10.0.0 or higher, the name of the package is newrelic-dotnet-agent. For .NET agent versions 9.9.0 or lower, the name of the package is newrelic-netcore20-agent.
The rest of this document refers to newrelic-dotnet-agent; replace this with the older name if you've an older agent version installed.
When you update to version 10.0.0 or higher from a lower one, you'll need to change the CORECLR_NEWRELIC_HOME and CORECLR_PROFILER_PATH environment variables due to the package name change.
Use one of the following methods to update to the latest version of the .NET agent of New Relic:
Update older .NET Framework agents (lower than 7.0)
If you're considering updating a .NET Framework agent version that's 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.
Important
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.
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 APM UI. Now these metrics won't 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:
Remove the following application setting in newrelic.config if it exists:
<appSettings>
<addkey="AsyncMode"value="false"/>
</appSettings>
Ensure your app's host has .NET 4.5 or higher installed.
Tell .NET to use the new ASP request processing pipeline by adding the following lines to your web.config:
Metrics that are not part of a transaction won't be displayed in the UI. Exception: You can view database and external metrics in their respective pages in the APM UI. Other such metrics (such as instrumented methods) can be made viewable by "wrapping" them in a custom transaction.
New Relic improved transaction naming. However, these changes can affect the transaction names of existing metrics, including key transactions, "alert on anything" metrics, and queries based on transaction names. You must recreate these settings using the new transaction name after the update.
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
The .NET agent of New Relic 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.2 or earlier
To update from a .NET agent version lower 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 update an old installer (2.1.3.494 or lower) or make other changes to environment variables. To resolve this problem, refer to Microsoft's documentation.