Install .NET Framework Agent

Getting 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.

Troubleshooting

After installing the agent if traces and metric data do not appear in the AppOptics dashboard, please review the Troubleshooting page for tips on how to resolve.

Diagnostics

A connectivity diagnostic tool is available with the .NET Framework Agent. To run it, open a command prompt and run the executable dotnet_diagnostic_tool.exe located in the agent install directory:

C:\Program Files\AppOptics\APM\dotnet> dotnet_diagnostic_tool.exe

The optional parameters are:

  • /ServiceKey : Service key to be used for the diagnostic tool. By default it uses the current service key configured configured globally for the host, it does not pick up any service keys defined at the <iisSites>, <applicationPools> or <applications> levels.
  • /Verbose : Enable printing to console of verbose level log messages from the diagnostic run.

For example, to verify connection using a specific service key:

C:\Program Files\AppOptics\APM\dotnet> dotnet_diagnostic_tool.exe /ServiceKey 0123456789abcde0123456789abcde0123456789abcde0123456789abcde1234:my-service

Look for the message Has connection succeeded? YES which indicates that the connection has succeeded.

If there are any errors, see the log file C:\Program Files\AppOptics\APM\dotnet\dotnet_diagnostic_tool.log.

The diagnostic tool provides exit code as below:

Exit Status Code Name Description
0 OK Diagnostics successful
101 UNKNOWN_ERROR Unexpected error. See error message for details
102 INVALID_FORMAT_ARGUMENT Argument passed to the diagnostic tool is not in valid format. For example the service key is too short. See error message for details
103 INVALID_ARGUMENTS Argument passed to the diagnostic tool is incorrect. For example using argument name not recognized by the diagnostic. See error message for details
104 INVALID_SERVICE_KEY Service key is rejected by AppOptics server
105 CONNECTION_FAILURE Failed to connect to the AppOptics server within the timeout limit of 5 seconds.
106 TRY_LATER AppOptics server rejected the diagnostic request with status TRY_LATER
107 LIMIT_EXCEEDED AppOptics server rejected the diagnostic request with status LIMIT_EXCEEDED

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:

    # to 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 specify "IISOnly,NonIISApplications" to instrument non-IIS applications as well.
DotNetAgent_Setup.exe [/SILENT | /VERYSILENT] /LOADINF="conf.inf" /COMPONENTS="IISOnly[,NonIISApplications]" [/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) and NonIISApplications.
  • /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.

Instrumenting Non-IIS Applications

To instrument non-IIS applications, add the following snippet to the agent config file, which is in Program Files\AppOptics\APM\dotnet:

<applications>
    <!-- add one line for each non-IIS application that should be instrumented -->
    <application name="non-iis_application_file_name.exe" />
</applications>

Note

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

The application will need to be restarted after updating the agent config file to start tracing.

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*.

Uninstalling the Agent

Note

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

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