Documentation forSolarWinds Observability

Install the .NET Library on Windows

Install the library

The .NET Library installer places the required DLL and config files in the %PROGRAMFILES% directory (typically C:\Program Files\) in the following location: %PROGRAMFILES%\SolarWinds\APM\dotnet.

Download the installer and complete one of the following sets of installation instructions, depending on the service you are instrumenting:

To install using a command prompt, see Install with the command line.

When the library is installed, requests to an instrumented application pool under IIS are traced, and the explorers and widgets are updated with data from the library.

Install for IIS hosted applications

  1. Enter iisreset /STOP in the command prompt to stop IIS.
  2. Run the .NET Library installer. During installation, provide your Service key when prompted and select either:
    • 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. Enter iisreset /RESTART in the command prompt to start IIS.

When the library is installed, requests to an instrumented application pool under IIS are traced, and the explorers and widgets are updated with data from the library.

Install for stand-alone, non-IIS applications

  1. Run the .NET Library installer. During installation, provide your Service key when prompted and select either:
    • Instrument NON-IIS .NET Framework Applications to instrument .NET Framework applications

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

      This sets the .NET Core profiler environment variables CORECLR_ENABLE_PROFILING and CORECLR_PROFILER at a system level.

  2. Configure the library:
    • If Instrument NON-IIS .NET Core Applications was selected during installation, dotnet.exe processes are automatically instrumented and do not need to be added in the library config 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 the .NET application to the solarwinds_apm.config config file. The name attribute must match 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.

Install with the command line

To automate the installation of the SolarWinds Observability .NET Library, the library can be installed through the command line.

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

    [Setup]
    service_key=*service-key*
    apm_collector=*SolarWinds-APM-Collector-endpoint*

    The apm_collector setting is optional and ensures the correct endpoint URI is used when sending data to the SolarWinds APM collector. To determine the correct endpoint for your SolarWinds APM collector, see Endpoint URIs.

  2. Run the following command in the command prompt:

    SolarWindsAPM_DotNetAgent_Setup.exe [/SILENT | /VERYSILENT] /LOADINF="conf.inf" /COMPONENTS="IISOnly[,NonIISApplications,IISCoreApplication,NonIISCoreApplication]" [/CLOSEAPPLICATIONS | /NOCLOSEAPPLICATIONS]

    Square brackets indicate optional parameters.

    The pipe character separates multiple choices within an option.

    For /COMPONENTS see Command line options for all available values. For example:

    /COMPONENTS="IISOnly,NonIISApplications"

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

Command line options

The following table lists the supported command line options for the installer:

Command line Description
/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.
/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 the speed of installation or uninstallation is important.
/NORESTART This flag prevents the installer from performing a system restart following an installation or uninstallation.
/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 uninstallation.
/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 installation progress window is not displayed.

Log file locations

SolarWinds Observability APM installers and libraries log detailed information about problems they run into, which can provide helpful information during troubleshooting.

  • Records of the instrumentation installation process are in %PROGRAMFILES%\SolarWinds\APM\dotnet\SolarWindsAPM.NETAgent.Install.<dd-mm-yyy>.log.<dd-mm-yyyy>.log.
  • Records of running instrumentation are in C:\Windows\Temp\SolarWinds\SolarWindsAPM_DotNetAgentLog*.

Troubleshooting

After installing the library, if traces and metric data do not appear in the Metrics Explorer and Traces Explorer, a diagnostic tool is available to help troubleshoot the problem. See Troubleshoot the .NET Library for information on how to use the diagnostic tool and for help resolving the issue.

Uninstall the library

The uninstallation executable is named uninsnnn.exe, where nnn is a number that starts at 000 and increments on each library re-installation. The following examples use unins000.exe.

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

  • Run the .NET Library uninstaller %PROGRAMFILES%\SolarWinds\APM\dotnet\unins000.exe, or follow the instructions below to uninstall the library using the command line.

    # square brackets indicate an optional parameters
    # the pipe character separates multiple choices within an option
    %PROGRAMFILES%\SolarWinds\APM\dotnet\unins000.exe [/SILENT | /VERYSILENT] [/CLOSEAPPLICATIONS | /NOCLOSEAPPLICATIONS]
  • Start IIS by running iisreset /START on 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.