---
title: Update the .NET agent
source: https://docs.newrelic.com/docs/apm/agents/net-agent/installation/update-net-agent
---
How to update the APM .NET agent.
## Check your .NET agent version [#your_version]
1. Refer to the [release notes](https://docs.newrelic.com/docs/releases/dotnet) 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.
## Before you start [#before-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:
- Docker: [for Windows](/install/dotnet/?deployment=windowsInstall&docker=yesDocker) | for [Linux](/install/dotnet/?deployment=linux&docker=yesDocker)
- [Nuget](https://docs.newrelic.com/docs/apm/agents/net-agent/install-guides/install-net-agent-using-nuget)
## Windows and Linux installs [#windows-linux]
Follow the update instructions for your agent:
- [Windows](#updating_net)
- [Linux](#updating_net_core)
## Update the .NET agent (Windows) [#updating_net]
> #### ⚠️ IMPORTANT
>
> Before updating:
>
> - Updating the agent requires **Administrator** rights in your Windows admin group. For more information, see the [permissions documentation](https://docs.newrelic.com/docs/apm/agents/net-agent/getting-started/net-agent-compatibility-requirements/#user-rights).
> - If your agent version is lower than 7.0 or you are using .NET Framework version 4.0 or lower, see [Update legacy .NET agent](#updating_older_net).
> - If your application is hosted in IIS, be sure to **stop IIS** before updating the .NET agent.
**Standard install**
1. Ensure that you have [.NET 4.5 or higher installed on your system](https://docs.newrelic.com/docs/apm/agents/net-agent/getting-started/net-agent-compatibility-requirements/#net-version-framework).
2. Stop IIS.
3. Download and run the appropriate MSI install package for your [architecture](https://docs.newrelic.com/docs/apm/agents/net-agent/getting-started/net-agent-compatibility-requirements/#architecture-framework):
- [32-bit installer](https://download.newrelic.com/dot_net_agent/latest_release/NewRelicDotNetAgent_x86.msi)
- [64-bit installer](https://download.newrelic.com/dot_net_agent/latest_release/NewRelicDotNetAgent_x64.msi)
4. After the installer package finishes, start IIS.
**Updating the agent with New Relic Azure site extension**
To update the .NET agent for an Azure Web App using the New Relic Azure site extension follow the installation instructions to:
- Remove the New Relic Azure site extension, this uninstalls the agent
- Re-install the latest version of the New Relic Azure site extension using [these installation instructions](/install/dotnet/?deployment=azure&azure=azuresiteextension), which installs the latest version of the agent.
- Restart the web app to start the updated agent.
## Update the .NET agent (Linux) [#updating_net_core]
> #### ⚠️ IMPORTANT
>
> 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:
**tar.gz or deb file**
1. Shut down your application(s).
2. Download the appropriate file for your [architecture](https://docs.newrelic.com/docs/apm/agents/net-agent/getting-started/net-agent-compatibility-requirements/#architecture-core) from the [download site](https://download.newrelic.com/dot_net_agent/latest_release/).
3. Install the file in your preferred install location. For the tar.gz file: Extract the zip file on top of your existing files.
4. Start your application(s).
**yum (CentOS, Oracle Linux, or RHEL)**
1. Shut down your application(s).
2. Use the following to update the agent:
```bash
sudo yum update newrelic-dotnet-agent
```
3. Start your applications(s).
**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:
```bash
sudo apt-get update && sudo apt-get install --only-upgrade newrelic-dotnet-agent
```
3. Start your application(s).
**rpm (CentOS, Oracle Linux, or RHEL)**
1. Shut down your application(s).
2. Download the appropriate rpm file for your [architecture](https://docs.newrelic.com/docs/apm/agents/net-agent/getting-started/net-agent-compatibility-requirements/#architecture-core) from the [download site](https://download.newrelic.com/dot_net_agent/latest_release/).
3. Use the following to update the agent:
```bash
sudo rpm -Uvh FILE_NAME.rpm
```
4. Start your application(s).
## Update older .NET Framework agents (lower than 7.0) [#updating_older_net]
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](#your_version). For a full list of agent changes, see the [.NET release notes](https://docs.newrelic.com/docs/release-notes/agent-release-notes/net-release-notes).
**.NET Framework legacy agent version details**
> #### ⚠️ 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](https://docs.newrelic.com/docs/apm/agents/net-agent/troubleshooting/technical-support-net-framework-40-or-lower/) 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](https://support.newrelic.com) or [download the agent](https://download.newrelic.com/). |
| 6.11 | Previously, [database](https://docs.newrelic.com/docs/apm/apm-ui-pages/monitoring/databases-page-view-operations-throughput-response-time/) and [external](https://docs.newrelic.com/docs/apm/apm-ui-pages/monitoring/external-services/external-services-intro/) 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](https://docs.newrelic.com/docs/apm/agents/net-agent/custom-instrumentation/create-transactions-xml-net/) to be able to view their metrics. |
| 6.0 | To get [async support](https://docs.newrelic.com/docs/apm/agents/net-agent/custom-instrumentation/create-transactions-xml-net/) 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: ```xml ``` - 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`: ```xml ``` OR Specify the .NET Framework version to be 4.5.2 or higher by adding the following lines to the `web.config`: ```xml ``` |
| 5.0 (for Web API) | To see Web API transactions, you must opt in to a [.NET framework bug fix](https://devblogs.microsoft.com/dotnet/all-about-httpruntime-targetframework/) 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're upgrading from .NET Framework agent to version 5.0 or higher. To apply the fix: - Ensure your app's host has .NET 4.5 installed. - Add this `appSetting` to your **web.config**: ```xml ``` For more information about this .NET framework bug, see: - [Why is HttpContext.Current null after await?](https://stackoverflow.com/questions/18383923/why-is-httpcontext-current-null-after-await) - [All about httpRuntime targetFramework](https://devblogs.microsoft.com/dotnet/all-about-httpruntime-targetframework/). |
| 5.0 (for metrics) | Metrics that are not part of a transaction won't be displayed in the UI. **Exception:** You can view [database](https://docs.newrelic.com/docs/apm/apm-ui-pages/monitoring/databases-page-view-operations-throughput-response-time/) and [external](https://docs.newrelic.com/docs/apm/apm-ui-pages/monitoring/external-services/external-services-intro/) 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](https://docs.newrelic.com/docs/apm/agents/net-agent/custom-instrumentation/create-transactions-xml-net/). Your [custom instrumentation](https://docs.newrelic.com/docs/apm/agents/net-agent/custom-instrumentation/introduction-net-custom-instrumentation/) may need to be updated to use [custom transactions](https://docs.newrelic.com/docs/apm/agents/net-agent/custom-instrumentation/create-transactions-xml-net/). For an example of what you'll see in the UI, see this [New Relic Online Technical Community post](https://support.newrelic.com/s/hubtopic/aAX8W0000008YBU/change-in-nonweb-transaction-reporting-with-version-5x). |
| 4.4 | New Relic improved transaction naming. However, these changes can affect the transaction names of existing metrics, including [key transactions](https://docs.newrelic.com/docs/apm/transactions/key-transactions/introduction-key-transactions/), "alert on anything" metrics, and [queries](https://docs.newrelic.com/docs/query-your-data/explore-query-data/query-builder/use-advanced-nrql-mode-query-data/) 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](https://learn.microsoft.com/en-us/windows/win32/procthread/changing-environment-variables). |