Installation on Windows (legacy agent)

The following content pertains to installation for the legacy AppOptics NET Agent.

Get the agent

There is a .NET agent installer which installs the required dlls and configuration files under Program Files\AppOptics\APM\dotnet.

• Download the installer from https://files.appoptics.com/dotnet/DotNetAgent_Setup.exe
• Stop IIS by running iisreset /STOP via the command line.
• Run the installer and provide your service key when requested. The installer also supports command line install
• Start IIS by running iisreset /START via the command line.
• Now requests to an instrumented application pool under IIS will be traced, and you'll see data in the AppOptics dashboard shortly.

The .NET Agent now supports both .NET Framework and .NET Core/5+ (which includes .NET Core, .NET 5, and later versions) applications. The install options are described in more detail below.

IIS Hosted Applications

To instrument IIS hosted applications:

1. Stop IIS: run iisreset /STOP via the command line.
2. Run the .NET agent installer, during installation select:

   • Instrument IIS .NET Framework Applications to instrument IIS Hosted .NET Framework applications

   • Instrument IIS .NET Core Applications to instrument IIS Hosted .NET Core/5+ applications

3. Restart IIS: run iisreset /START via the command line.

Requests to an instrumented application pool under IIS will be traced, and you'll see data in the AppOptics dashboard shortly.

Non-IIS Applications

To instrument non-IIS applications

1. Run the .NET agent installer, during installation select:

   • Instrument NON-IIS .NET Framework Applications to instrument Non-IIS (e.g. standalone) .NET Framework applications

   • Instrument NON-IIS .NET Core Applications to instrument Non-IIS (e.g. standalone) .NET Core/5+ applications.

     This will set the .NET Core profiler environment variables CORECLR_ENABLE_PROFILING and CORECLR_PROFILER at a SYSTEM level.

2. Configure the agent:
   • If Instrument NON-IIS .NET Core Applications was selected during install, dotnet.exe processes are automatically instrumented and do not need to be added in the agent configuration file.

   • If you are instrumenting a non-IIS .NET Framework application or a .NET Core application that is run directly (instead of under the dotnet.exe process), add an <application> node for this .NET application to the \Program Files\AppOptics\APM\dotnet\agent.config configuration file. The name attribute should be set to the file name of the executable.

     <applications> 
         <!-- add one line for each non-IIS application that should be instrumented --> 
         <application name="non-iis-framework_application.exe" /> 
         <application name="non-iis-dotnet-core-executable" /> 
     </applications> 

   • Standalone WCF services will be instrumented automatically.
   • Other types of non-IIS .NET Framework applications must be instrumented using the custom instrumentation SDK.

3. Restart the application to start tracing.

Command Line Install

To automate the installation of the AppOptics .NET Agent, the agent can be installed via the command line.

1. Create a file called conf.inf with the following contents, and place it in the same directory as your installer.

   [Setup]
   service_key=*service-key*

2. Run following command:

   # Install the .NET Agent via the command line. 
   # Square brackets indicate an optional parameters. 
   # The pipe character separates multiple choices within an option. 
   # For /COMPONENTS see the command line options documentation for 
   # all available values.  For example: 
   #   /COMPONENTS="IISOnly,NonIISApplications"  
   
   DotNetAgent_Setup.exe [/SILENT | /VERYSILENT] /LOADINF="conf.inf" /COMPONENTS="IISOnly[,NonIISApplications,IISCoreApplication,NonIISCoreApplication]" [/CLOSEAPPLICATIONS | /NOCLOSEAPPLICATIONS] 

3. To start tracing, restart the application pools in which your apps are running via the iisreset command-line tool.

Command Line Options

Below is the list of supported command line options for the installer:

• /CLOSEAPPLICATIONS – this flag instructs the installer to close applications using files that need to be updated, if possible.
• /COMPONENTS="IISOnly" – this option allows specifying a comma separated list of components selected. Valid components are:
  • IISOnly (default) – instrument IIS .NET Framework applications
  • NonIISApplications – instrument non-IIS .NET Framework applications
  • IISCoreApplications – instrument IIS .NET Core/5+ applications
  • NonIISCoreApplications – instrument non-IIS .NET Core/5+ applications
• /LOADINF="conf.inf" – this option instructs the installer to load settings from the specified file.
• /LOG="filename" – the installer currently creates a "Setup Log .txt" file but the uninstall process doesn’t create a log file. The "/LOG=filename" option can be used to create a log file for the uninstall.
• /NOCLOSEAPPLICATIONS – this flag prevents the installer from closing applications using files that need to be updated.
• /NOCONNECTIVITYCHECK – this flag prevents the installer from running the connectivity diagnostic checks. The diagnostics can take 2 to 3 seconds so this flag can be used when install/uninstall speed is important.
• /NORESTART – this flag prevents the installer from running a system restart following an install or uninstall.
• /RESTARTEXITCODE=exitcode – this option allows specifying a custom exit code that the installer returns if the system needs to be restarted following a successful installation or uninstall.
• /SILENT – this flag instructs the installer to be silent, the installation progress window is displayed.
• /VERYSILENT – this flag instructs the installer to be very silent, the install progress window is not displayed.

Log File Locations

AppOptics installers and agents log detailed information about problems they run into, which can provide helpful information during troubleshooting.

• Records of the instrumentation install process are in:
  • C:\Program Files\AppOptics\APM\dotnet\instrumentation_setup.log for agent versions up to 3.5.0
  • C:\Program Files\AppOptics\APM\dotnet\AppOptics.NETAgent.Install.<dd-mm-yyyy>.log for agents starting from version 3.5.1
• Records of running instrumentation are in C:\Windows\TEMP\AppOptics\DotNetAgentLog*.

Troubleshooting

After installing the agent if traces and metric data do not appear in the AppOptics dashboard, a diagnostic tool is available to help troubleshoot the problem. Review the Troubleshooting page for information on how to use the diagnostic tool and for help resolving the issue.

Uninstalling the Agent

Having the system environment variable UI open during uninstallation will result in the system environment variables not been removed.

You can uninstall the Agent using any of the following methods:

• Uninstall using the agent uninstaller:

  The uninstall executable is named unins<nnn>.exe, where nnn is a number that starts at 000 and increments on each agent re-installation. The examples below will use unins000.exe.

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

     To stop IIS, run the command iisreset /stop.

     To stop a Windows service, run the command sc stop ServiceName. Make sure to replace ServiceName with the actual service name.

     Ensure that IIS is completely stopped before performing any installation or uninstallation tasks.

  2. Run the .NET agent uninstaller C:\Program Files\AppOptics\APM\dotnet\unins000.exe, or follow the instructions below to uninstall the agent via the command line.

     # square brackets indicate an optional parameters
     # the pipe character separates multiple choices within an option
     C:\Program Files\AppOptics\APM\dotnet\unins000.exe [/SILENT | /VERYSILENT] [/CLOSEAPPLICATIONS | /NOCLOSEAPPLICATIONS]

  3. Start IIS by running iisreset /START via the command line.

• Uninstall using the Settings app:

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

     To stop IIS, run the command iisreset /stop.

     To stop a Windows service, run the command sc stop ServiceName. Make sure to replace ServiceName with the actual service name.

     Ensure that IIS is completely stopped before performing any installation or uninstallation tasks.

  2. Click the Windows icon, and then click the gear icon to open the Settings app.

  3. Go to "Apps & features".

  4. Find "AppOptics .NET Agent", click it, and choose "Uninstall".

• Uninstall using "Programs and Features":

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

     To stop IIS, run the command iisreset /stop.

     To stop a Windows service, run the command sc stop ServiceName. Make sure to replace ServiceName with the actual service name.

     Ensure that IIS is completely stopped before performing any installation or uninstallation tasks.

  2. Type "Control Panel" in the Windows Search bar and select it.

  3. Under Programs, choose "Programs and Features".

  4. Find "AppOptics .NET Agent", right-click it, and choose "Uninstall".

Was AppOptics uninstalled successfully?

You can use either of the following methods to verify the removal.

Automatic verification

You can use a script to verify that the AppOptics .NET Agent has been uninstalled successfully:

1. Download the script from https://agent-binaries.cloud.solarwinds.com/apm/dotnet/latest/appoptics-check-uninstall.ps1

2. Open a new PowerShell session as Administrator and run the following command:

   .\appoptics-check-uninstall.ps1

   The script detects items that were not properly removed by the uninstaller. Items marked with "[ FOUND ]" should be removed.

   Running the script multiple times is safe, because it doesn’t make any changes to the system.

   If you modify environment variables, those changes will take effect only in a newly launched system environment variable UI or a new PowerShell session that runs a helper script.

Manual verification

To manually verify that the AppOptics .NET Agent has been uninstalled successfully, complete the following checks:

1. Verify that AppOptics .NET Agent is not listed under "Apps & features" or "Programs and Features."

2. Verify that all files except agent.config and installer_history.log have been deleted from the %PROGRAMFILES%/AppOptics/APM/dotnet/ directory.

3. Verify that the system PATH doesn't contain the %PROGRAMFILES%/AppOptics/APM/dotnet/x64 or %PROGRAMFILES%/AppOptics/APM/dotnet/x86 directories.

4. Verify that IIS registry entries for WAS and W3SVC don't contain the Environment key. Open RegEdit, and check the following entries:

   • HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Environment

   • HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS\Environment

   If the Environment key is present, it should not include any of the following entries:

   • APPOPTICS_HOME_APM_DOTNET=C:\Program Files\AppOptics\APM\dotnet\
   • COR_ENABLE_PROFILING=1
   • COR_PROFILER={824293AD-22E2-4DAA-BC28-166C140543BE}
   • CORECLR_ENABLE_PROFILING=1
   • CORECLR_PROFILER={824293AD-22E2-4DAA-BC28-166C140543BE}

5. Open RegEdit, and check that the AppOptics profiler is not registered. The registry should not contain any of the following entries:

   • HKEY_LOCAL_MACHINE\Software\Classes\CLSID\{824293AD-22E2-4DAA-BC28-166C140543BE}

   • HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Wow6432Node\CLSID\{824293AD-22E2-4DAA-BC28-166C140543BE}

   • HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Classes\CLSID\{824293AD-22E2-4DAA-BC28-166C140543BE}

Items that might not be removed

After you uninstall the AppOptics .NET Agent (4.3.x), some items are not removed even after a successful uninstallation:

• The installation directory %PROGRAMFILES%/AppOptics/APM/dotnet (intended for future upgrades)

• The %PROGRAMFILES%/AppOptics/APM/dotnet/x64 and %PROGRAMFILES%/AppOptics/APM/dotnet/x86 directories in the System PATH

• The registry entry HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Environment

• Assembly C:\Windows\Microsoft.NET\assembly\GAC_MSIL\AppOptics.InstrumentersAspNetCore\v4.0_4.3.3.0__0f268bfac2721a2c\AppOptics.InstrumentersAspNetCore.dll

• Assembly C:\Windows\Microsoft.NET\assembly\GAC_MSIL\oboe.managed.core\v4.0_4.3.3.0__0f268bfac2721a2c\oboe.managed.core.dll

Uninstall AppOptics after a reinstallation on Windows

Continue with the following steps only if the uninstall was not successful after purging the AppOptics .NET Agent.

Reinstalling AppOptics allows the installer to fix corrupted entries left by an unsuccessful uninstallation. After it is reinstalled, the uninstaller will run on a fresh installation.

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

   To stop IIS, run the command iisreset /stop.

   To stop a Windows service, run the command sc stop ServiceName. Make sure to replace ServiceName with the actual service name.

   Ensure that IIS is completely stopped before performing any installation or uninstallation tasks.

2. Back up %PROGRAMFILES%/AppOptics/APM/dotnet/agent.config to a safe location.

3. Install the AppOptics .NET Agent. During installation, in the component selection dialog, select to install all components. Before starting the installation, make sure that IIS is fully stopped.

4. Restart the workstation.

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

   To stop IIS, run the command iisreset /stop.

   To stop a Windows service, run the command sc stop ServiceName. Make sure to replace ServiceName with the actual service name.

   Ensure that IIS is completely stopped before performing any installation or uninstallation tasks.

6. Uninstall the AppOptics .NET Agent. Before starting the uninstallation, make sure that IIS is fully stopped.

7. Restart the workstation.

8. Purge the AppOptics .NET Agent.

9. Restart the workstation.

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

    To start IIS, run the command iisreset /start.

    To start a Windows service, run the command sc start ServiceName. Make sure to replace ServiceName with the actual service name.

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.