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:
Table of 9.x Windows installation asset names and their 10.x equivalents
|Auto-install for .NET Framework and .NET Core/.NET (64-bit)
|Auto-install for .NET Framework and .NET Core/.NET (32-bit)
|ZIP archive of agent assets for .NET Framework only (64-bit)
|ZIP archive of agent assets for .NET Framework only (32-bit)
|ZIP archive of agent assets for .NET Core/.NET only (64-bit)
|ZIP archive of agent assets for .NET Core/.NET only (32-bit)
Linux installer packages name change
Starting from v10.x, the name of the agent install packages for Linux is changing from
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.
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.
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.
For safety, you should make a backup copy of all files in
/usr/local/newrelic-netcore20-agentbefore continuing to the next step.
Shut down any .NET applications currently being monitored.
Follow the instructions for the package manager appropriate for your Linux system:
Update the profiling environment variables. The exact config you should use changes based on your specific variables.
- 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
If you are on a Debian-based (apt/dpkg) system:bash$sudo dpkg -P newrelic-netcore20-agent
/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 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.