Skip to content

Latest commit

 

History

History
167 lines (123 loc) · 9.31 KB

9x-to-10x-agent-migration-guide.mdx

File metadata and controls

167 lines (123 loc) · 9.31 KB
Raw
title tags metaDescription freshnessValidatedDate
.NET agent 9.x to 10.x migration guide
Agents
NET agent
Migration guides
This guide helps New Relic .NET agent users migrate from 9.x versions to 10.x
never

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

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:

    1. Update the local package list: 
       ```bash
   sudo apt update
   ```
2. Upgrade the agent:

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

    <Collapser id="clamshell_debian_ubuntu_mint_dpkg" title="Upgrade with dpkg (Debian, Linux Mint, or Ubuntu)"

    1. Go to <DoNotTranslate>**[download.newrelic.com/dot_net_agent/latest_release](https://download.newrelic.com/dot_net_agent/latest_release/)**</DoNotTranslate>, and copy the URL that corresponds to your [architecture](/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
   ```

    <Collapser id="clamshell_centos_rhel_oracle_yum" title="Upgrade with yum (CentOS, Oracle Linux, or RHEL)"

    <Callout variant="important">
  New Relic does not currently offer Linux rpm packages for ARM64. Instead, [leverage the tarball to install](#clamshell_tarball) on these platforms.
</Callout>

1. Upgrade the agent:

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

    <Collapser id="clamshell_centos_rhel_oracle_rpm" title="Upgrade with rpm (CentOS, Oracle Linux, or RHEL)"

    <Callout variant="important">
  New Relic does not currently offer Linux rpm packages for ARM64. Instead, [leverage the tarball to install](#clamshell_tarball) on these platforms.
</Callout>

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](/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.

    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:

    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.