• EnglishEspañol日本語한국어Português
  • Log inStart now

.NET agent 9.x to 10.x 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 and .NET Core 3.0 and lower have reached end of support. 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 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 filenameUsed for10.x filename
newrelic-agent-win-x64-VERSION.msiAuto-install for .NET Framework and .NET Core/.NET (64-bit)NewRelicDotNetAgent_VERSION_x64.msi
newrelic-agent-win-x86-VERSION.msiAuto-install for .NET Framework and .NET Core/.NET (32-bit)NewRelicDotNetAgent_VERSION_x86.msi
newrelic-agent-win-x64-VERSION.zipZIP archive of agent assets for .NET Framework only (64-bit)NewRelicDotNetAgent_VERSION_x64.zip
newrelic-agent-win-x86-VERSION.zipZIP archive of agent assets for .NET Framework only (32-bit)NewRelicDotNetAgent_VERSION_x86.zip
newrelic-netcore20-agent-win-x64-VERSION.zipZIP archive of agent assets for .NET Core/.NET only (64-bit)NewRelicDotNetAgent_VERSION_x64.zip
newrelic-netcore20-agent-win-x86-VERSION.zipZIP 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


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:

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

  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:

    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):

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

Shorter version numbers in installer filenames

The New Relic .NET agent has been using Semantic Versioning 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.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.