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

• Stop IIS by running iisreset /STOP via the command line.

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

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

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.