Install .NET Framework Agent¶

Getting the agent
Troubleshooting
Diagnostics
Command Line Install
- Command Line Options
Instrumenting Non-IIS Applications
Log File Locations
Uninstalling the 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.

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

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]

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 ¶

If you decided to instrument non-IIS applications add the following snippet to the agent config file, which is in Program Files\AppOptics\APM\dotnet. The application will need to be restarted after updating the agent config file to start tracing.

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

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