Documentation forSolarWinds Observability SaaS

Install the .NET Library on Windows

Before you start

Verify the following to ensure the library can collect and transmit data:

  • The platform where your APM library will be installed is supported.

  • Your application components are supported by the library.

  • Your firewall configuration permits TCP/HTTPS/TLS outbound connections to apm.collector.xx-yy.cloud.solarwinds.com (where xx-yy is determined by the URL you use to access SolarWinds Observability SaaS, described in Data centers and endpoint URIs) using port 443. See Firewall or access control requirements.

    If your firewall or access control requirements do not allow such connections, configure the library to send data through a proxy.

Do not run other APM libraries alongside the SolarWinds Observability .NET Library. See Do you have another profiler installed?.

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.

Installation 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 and ingestion endpoint 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 6+ 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.

Installation for stand-alone, non-IIS applications

  1. Run the .NET Library installer. During installation, provide your Service key and ingestion endpoint 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 6+ 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=YourServiceKey
apm_collector=YourSolarWindsApmCollectorEndpoint

    Modify the following text:

    • Replace YourServiceKey with the Service key you are using to identify your account and the service being instrumented. 

      The Service key should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

      The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.

    • Replace YourSolarWindsApmCollectorEndpoint with the correct SolarWinds APM collector endpoint for your organization.

      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 Data centers and 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 6+ applications
NonIISCoreApplications Instrument non-IIS .NET 6+ 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*.

Environment Variables

Depending on the components selected, the SolarWinds Observability APM Library installer creates the following the environment variables.

Instrument IIS .NET Framework Applications

  • Environment variables are set in the registry for IIS.

  • Registry locations:

    • HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\W3SVC\Environment

    • HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\WAS\Environment

  • Environment variables:

    • COR_ENABLE_PROFILING=1

    • COR_PROFILER={AAAA7777-11FE-4F94-8EDA-312C0EDF4141}

    • SW_APM_HOME_DOTNET=C:\Program Files\SolarWinds\APM\dotnet\

Instrument IIS .NET Core Applications

  • Environment variables are set in the registry for IIS.

  • Registry locations:

    • HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\W3SVC\Environment

    • HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\WAS\Environment

  • Environment variables:

    • CORECLR_ENABLE_PROFILING=1

    • CORECLR_PROFILER={AAAA7777-11FE-4F94-8EDA-312C0EDF4141}

    • SW_APM_HOME_DOTNET=C:\Program Files\SolarWinds\APM\dotnet\

Instrument NON-IIS .NET Framework Applications:

  • System Environment variables:

    • COR_ENABLE_PROFILING=1

    • COR_PROFILER={AAAA7777-11FE-4F94-8EDA-312C0EDF4141}

    • SW_APM_HOME_DOTNET=C:\Program Files\SolarWinds\APM\dotnet\

Instrument NON-IIS .NET Core Applications:

  • System Environment variables:

    • CORECLR_ENABLE_PROFILING=1

    • CORECLR_PROFILER={AAAA7777-11FE-4F94-8EDA-312C0EDF4141}

    • SW_APM_HOME_DOTNET=C:\Program Files\SolarWinds\APM\dotnet\

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.