---
title: .NET agent 9.x to 10.x migration guide
source: https://docs.newrelic.com/docs/apm/agents/net-agent/getting-started/9x-to-10x-agent-migration-guide
---

This guide outlines the major changes between the 9.x and 10.x versions of the .NET agent, issues that you may encounter while upgrading, and how to migrate successfully to version 9.x.

Main changes include:

-   The .NET agent no longer supports frameworks designated as end-of-life
-   Removal of deprecated scriptable installers
-   Removal of deprecated instrumentation
-   Windows installation assets consolidation and name changes
-   Linux installer packages name change
-   Shorter version number in installer filenames

## The .NET agent no longer supports frameworks designated as end-of-life

Microsoft announced that [.NET Framework 4.6.1 and lower](https://docs.microsoft.com/en-us/lifecycle/products/microsoft-net-framework) and .NET Core 3.0 and lower have reached [end of support](https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core). Designating old frameworks as end-of-life ensures we're devoting resources to improving newer versions of those frameworks.

It is recommended that customers migrate their applications to use the supported framework versions. In the event where framework migration isn't an option, customers can still instrument their applications with the 9.x version .NET agent.

## Removal of deprecated scriptable installer

Starting from v10.x, we will stop providing scriptable installers from our download site due to low usage. If you use the scriptable installer to automate the .NET agent installation process, consider using the MSI installer with command line options in your script or building your own installation script with the zip archive .NET agent from our [download site](https://download.newrelic.com/dot_net_agent/latest_release/) moving forward.

## Removal of deprecated instrumentation

Starting from v10.x, the .NET agent stops instrumenting Castle MonoRail. Customers can still use older versions of the .NET agent to instrument this library.

## Windows installation assets consolidation and name changes

In previous versions, we published separate ZIP archives for manual installation of agent assets for .NET Framework and .NET Core/.NET 5+ on Windows.  These have been consolidated into a single ZIP archive containing both .NET Framework and .NET Core/.NET 5+ agent assets for manual Windows installation (both 64-bit and 32-bit versions are still available).  This makes these manual ZIP archives similar to the existing MSI automated installers which install both .NET Framework and .NET Core/.NET 5+ assets.

We have also renamed the MSI and ZIP files to all have the same base file name: `NewRelicDotNetAgent`.

### Table of 9.x Windows installation asset names and their 10.x equivalents

| 9.x filename                                 | Used for                                                     | 10.x filename                       |
| -------------------------------------------- | ------------------------------------------------------------ | ----------------------------------- |
| newrelic-agent-win-x64-VERSION.msi           | Auto-install for .NET Framework and .NET Core/.NET (64-bit)  | NewRelicDotNetAgent_VERSION_x64.msi |
| newrelic-agent-win-x86-VERSION.msi           | Auto-install for .NET Framework and .NET Core/.NET (32-bit)  | NewRelicDotNetAgent_VERSION_x86.msi |
| newrelic-agent-win-x64-VERSION.zip           | ZIP archive of agent assets for .NET Framework only (64-bit) | NewRelicDotNetAgent_VERSION_x64.zip |
| newrelic-agent-win-x86-VERSION.zip           | ZIP archive of agent assets for .NET Framework only (32-bit) | NewRelicDotNetAgent_VERSION_x86.zip |
| newrelic-netcore20-agent-win-x64-VERSION.zip | ZIP archive of agent assets for .NET Core/.NET only (64-bit) | NewRelicDotNetAgent_VERSION_x64.zip |
| newrelic-netcore20-agent-win-x86-VERSION.zip | ZIP archive of agent assets for .NET Core/.NET only (32-bit) | NewRelicDotNetAgent_VERSION_x86.zip |

## Linux installer packages name change

Starting from v10.x, the name of the agent install packages for Linux is changing from `newrelic-netcore20-agent` to `newrelic-dotnet-agent`. We feel that the name `netcore20` has been confusing since we have supported versions of .NET Core greater than 2.0 as they have been released, and as of agent version 10.0 we no longer support versions of .NET Core older than 3.1.

The new `newrelic-dotnet-agent` packages are marked as conflicting with and replacing (DEB) or obsoleting (RPM) the older `newrelic-netcore20-agent` packages. Your system's package manager will not allow both to be installed at the same time.

### Upgrading from `newrelic-netcore20-agent` to `newrelic-dotnet-agent`

> #### ⚠️ IMPORTANT
>
> The upgrade process will migrate your `newrelic.config` and any XML custom instrumentation files from the previous agent installation in `/usr/local/newrelic-netcore20-agent` to the new installation location in `/usr/local/newrelic-dotnet-agent`. Log files and any other custom data will **not** automatically be migrated.

1.  For safety, you should make a backup copy of all files in `/usr/local/newrelic-netcore20-agent` before continuing to the next step.

2.  Shut down any .NET applications currently being monitored.

3.  Follow the instructions for the package manager appropriate for your Linux system:

    **Upgrade with apt (Debian, Linux Mint, or Ubuntu)**

    1.  Update the local package list:

        ```bash
        sudo apt update
        ```
    2.  Upgrade the agent:

        ```bash
        sudo apt install newrelic-dotnet-agent
        ```

    **Upgrade with dpkg (Debian, Linux Mint, or Ubuntu)**

    1.  Go to **[download.newrelic.com/dot_net_agent/latest_release](https://download.newrelic.com/dot_net_agent/latest_release/)**, and copy the URL that corresponds to your [architecture](https://docs.newrelic.com/docs/agents/net-agent/getting-started/compatibility-requirements-net-agent#architecture) and to the latest `newrelic-dotnet-agent` .deb package.
    2.  Download the package with `wget`, replacing `https://LINK_TO_PACKAGE` with the full URL of the package:

        ```bash
        wget -L https://LINK_TO_PACKAGE
        ```
    3.  Upgrade the agent, replacing `VERSION` with the current version:

        ```bash
        sudo dpkg -i newrelic-dotnet-agent_VERSION_ARCHITECTURE.deb
        ```

    **Upgrade with yum (CentOS, Oracle Linux, or RHEL)**

    > #### ⚠️ IMPORTANT
    >
    > New Relic does not currently offer Linux rpm packages for ARM64. Instead, [leverage the tarball to install](#clamshell_tarball) on these platforms.

    1.  Upgrade the agent:

        ```bash
        sudo yum install newrelic-dotnet-agent
        ```

    **Upgrade with rpm (CentOS, Oracle Linux, or RHEL)**

    > #### ⚠️ IMPORTANT
    >
    > New Relic does not currently offer Linux rpm packages for ARM64. Instead, [leverage the tarball to install](#clamshell_tarball) on these platforms.

    1.  Go to [download.newrelic.com/dot_net_agent/latest_release](https://download.newrelic.com/dot_net_agent/latest_release/), and copy the URL that corresponds to your [architecture](https://docs.newrelic.com/docs/agents/net-agent/getting-started/compatibility-requirements-net-agent#architecture) and to the latest `newrelic-dotnet-agent` .rpm package.
    2.  Download the package with `wget`, replacing `https://LINK_TO_PACKAGE` with the full URL of the package:

        ```bash
        wget -L https://LINK_TO_PACKAGE
        ```
    3.  Upgrade the agent, replacing `VERSION` with the current version:

        ```bash
        sudo rpm -U newrelic-dotnet-agent_VERSION.x86_64.rpm
        ```

4.  Update the profiling environment variables. The exact config you should use changes based on your specific variables.

    ```ini
    CORECLR_ENABLE_PROFILING="1"
    CORECLR_PROFILER="{36032161-FFC0-4B61-B559-F6C5D41BAE5A}"
    CORECLR_NEWRELIC_HOME="/usr/local/newrelic-dotnet-agent"
    CORECLR_PROFILER_PATH="/usr/local/newrelic-dotnet-agent/libNewRelicProfiler.so"
    ```

5.  Start your app and wait for data to appear.

Once you are satisfied that the migration is successful, perform the following steps to clean up remaining artifacts from the previous `newrelic-netcore20-agent` installation:

1.  If you are on a Debian-based (apt/dpkg) system:

    ```bash
    sudo dpkg -P newrelic-netcore20-agent
    ```

2.  Remove `/usr/local/newrelic-netcore20-agent` (applies to both Debian-based (apt/dpkg) and RPM-based (yum/rpm) scenarios):

    ```bash
    sudo rm -rf /usr/local/newrelic-netcore20-agent
    ```

## Shorter version numbers in installer filenames

The New Relic .NET agent has been using [Semantic Versioning](https://semver.org/) since agent version 8.28.0.  SemVer uses three numbers to version a release: major, minor, and patch. However, our installer filenames have continued to use four numbers, with the fourth version number always being zero.  Moving forward, we are dropping this meaningless and potentially confusing fourth number from the version strings found in our installer filenames. This change applies to both Windows and Linux installer files.