.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

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

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

      Copy

      $
      sudo apt update

   2. Upgrade the agent:

      bash

      Copy

      $
      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, and copy the URL that corresponds to your 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

      Copy

      $
      wget -L https://LINK_TO_PACKAGE

   3. Upgrade the agent, replacing VERSION with the current version:

      bash

      Copy

      $
      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 on these platforms.

   1. Upgrade the agent:

      bash

      Copy

      $
      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 on these platforms.

   1. Go to download.newrelic.com/dot_net_agent/latest_release, and copy the URL that corresponds to your 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

      Copy

      $
      wget -L https://LINK_TO_PACKAGE

   3. Upgrade the agent, replacing VERSION with the current version:

      bash

      Copy

      $
      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.

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

   Copy

   $
   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

   Copy

   $
   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.