Upgrading the .NET Agent

AppOptics agents are no longer receiving updates. The new SolarWinds Observability libraries are regularly updated with new features and improvements. If you are still relying on the AppOptics agents and your components are supported by the new libraries, consider migrating to SolarWinds Observability.

Upgrading to the SolarWinds Observability .NET Library

The .NET Instrumentation Library for SolarWinds Observability is compatible with the AppOptics collector. SolarWinds Observability libraries are not compatible with AppOptics agents. Do not use a mix of SolarWinds Observability libraries and AppOptics agents to instrument applications that are part of a distributed trace.

Complete migration

SolarWinds recommends that you migrate completely from AppOptics to SolarWinds Observability. For more information about a complete migrations, see Migrate from AppOptics to SolarWinds Observability SaaS. To upgrade to the SolarWinds Observability .NET Library as part of a complete migration, see Migrate the .NET Library from AppOptics to SolarWinds Observability.

Partial migration

Alternatively, you can upgrade to the SolarWinds Observability .NET Library but send data to AppOptics.

Migrate from AppOptics on Windows

1. Stop the applications that are being instrumented (for example, Windows services and IIS).

   To stop IIS, run the command iisreset /stop.

2. Uninstall the AppOptics .NET Agent.

3. Download the installer, and install the SolarWindsAPM .NET Library.

4. Set a valid AppOptics service key. See the SolarWinds Observability configuration options for the new configuration file and environment variable names.

5. Set the collector configuration option to the AppOptics endpoint collector.appoptics.com:443. Use a config option or an environment variable to override the default APM collector endpoint.

6. If you have custom configurations in the AppOptics .NET Library configuration file, you can copy them to the SolarWindsAPM .NET Agent configuration file. For example, you can copy configuration sections such as application elements.

   The API token portion of the serviceKey attribute must be updated to be a valid SolarWinds Observability token.

   The configuration files can be found in the following locations:

   • AppOptics: %PROGRAMFILES%/AppOptics/APM/dotnet/agent.config

   • SolarWinds Observability: %PROGRAMFILES%/SolarWinds/APM/dotnet/solarwinds_apm.config

   For more information on configuration settings, see Configure the .NET Library.

7. Start the applications to be instrumented (for example, Windows services and IIS).

   To start IIS, run the command iisreset /start.

Migrate from AppOptics on Linux

1. Stop the applications that are being instrumented.

2. Remove the AppOptics .NET Agent files.

   The default location is ${HOME}/appoptics, but the files can be installed elsewhere.

3. Download from the installer from https://agent-binaries.cloud.solarwinds.com/apm/dotnet/latest/solarwinds-apm-dotnet-agent-package.tgz. Then install the SolarWindsAPM .NET Agent.

4. Set a valid AppOptics service key. See the SolarWinds Observability configuration options for the new configuration file and environment variable names.

5. Set the collector configuration option to the AppOptics endpoint collector.appoptics.com:443. Use a config option or an environment variable to override the default APM collector endpoint.

6. Update the environment variables.

7. If you have custom configurations in the AppOptics .NET Agent configuration file, you can copy them to the SolarWindsAPM .NET Agent configuration file. For example, you can copy configuration sections such as application elements.

   The API token portion of the serviceKey attribute must be updated to be a valid SolarWinds Observability token.

   The configuration files can be found in the following locations:

   • AppOptics: agent.config

   • SolarWinds Observability: solarwinds_apm.config

   For more information on configuration settings, see Configure the .NET Library.

8. Start the applications.

Upgrade to a newer version of the legacy AppOptics Agent

Upgrading IIS Only instrumentation

1. Run iisreset /STOP to stop IIS
2. Run the uninstaller: C:\Program Files\AppOptics\APM\dotnet\unins000.exe The uninstaller filename has the format unins<nnn>.exe where nnn will increment on reinstalls.
3. Download the latest .NET Agent from https://files.appoptics.com/dotnet/DotNetAgent_Setup.exe
4. Run the new installer
5. Run iisreset /START to start IIS

Upgrading IIS and non-IIS instrumentation

These steps document how to upgrade the .NET agent when both IIS and non-IIS services are being instrumented.

1. Run iisreset /STOP to stop IIS
2. Stop services configured in the applications section of the agent.config file
3. Run the uninstaller: C:\Program Files\AppOptics\APM\dotnet\unins000.exe
4. Download the latest .NET Agent from https://files.appoptics.com/dotnet/DotNetAgent_Setup.exe
5. Run the new .NET agent installer
6. Run iisreset /START to start IIS
7. Restart any services stopped in Step 2

AppOptics.Instrumentation NuGet Package

The AppOptics.Instrumentation NuGet package has been deprecated and is no longer supported. The package has been replaced with the AppOptics.Agent NuGet package. In addition to providing the same functionality as the AppOptics.Instrumentation NuGet package, the AppOptics.Agent package also provides automatic instrumentation support. See AppOptics.Agent NuGet package (legacy agent).