Download PDF
Download page Upgrade the .NET Agent for Windows.
Upgrade the .NET Agent for Windows
The MSI installer package for AppDynamics .NET Agent installs updated agent files and maintains legacy configurations. When you upgrade from .NET Agent < 3.9, or prior to 3.9, you must first uninstall the existing .NET Agent.
If you use the AppDynamics Azure Site Extension, see Install the AppDynamics Azure Site Extension for .NET.
Requirements
- Before you begin, review the Release Notes.
- AppDynamics requires an account access key for agent connections to single-tenant Controller accounts. AppDynamics <= 4.1 only required an account access key for multi-tenant Controller accounts.
If you have a single-tenant Controller, you can locate the account access key in the Controller under Settings > License > Account. You must be a member of a role with the View License account level permission, see Create and Manage Custom Roles.
The .NET Agent only supports in-place upgrade for these versions:
- >= 3.9
Major and minor releases after the currently installed version. For patch releases, you must uninstall the existing agent before upgrading.
For example, to install the patch release 4.1.0.1 over 4.1.0.0, uninstall the existing agent before upgrading.
Upgrade the .NET Agent from >= 3.9
Except for patches to the current version, you do not need to uninstall the old agent first when you upgrade from the .NET Agent >= 3.9.
- Stop
w3wp
processes for instrumented IIS applications. Stop instrumented Windows services or standalone applications. - Download the MSI installer package from AppDynamics Downloads.
- Launch an elevated command prompt with full administrator privileges. Logging on to Windows as a member of the Administrators group does not grant sufficient permissions to run the installer. See Start a Command Prompt as an Administrator.
- If you use a single-tenant Controller account, in the Controller click Settings > License > Account to view your access key.
Run a command-line agent install. For single-tenant Controller accounts, specify your account access key using the
AD_CONTROLLER_ACCOUNT_ACCESS_KEY
parameter. For example:msiexec /i "%USERPROFILE%\Downloads\dotNetAgentSetup.msi" /l log.txt /q AD_CONTROLLER_ACCOUNT_ACCESS_KEY=changeme
The installation runs silently in the background.
If you forget to add the account access key for a single-tenant Controller account, you can run the Agent Configuration Utility or manually add it to the config.xml later, see Account Element.
(Optional) Add the parameter
INSTALLDIR=<path to installation directory>
if you have changed the installation directory. For example:msiexec /i "%USERPROFILE%\Downloads\dotNetAgentSetup.msi" /l log.txt /q AD_CONTROLLER_ACCOUNT_ACCESS_KEY=changeme INSTALLDIR=<path to installation directory>
- Restart IIS:
- Launch the AppDynamics Agent Configuration utility and click Restart IIS on the Configuration Summary window.
or - Execute
iisreset
from the command line.
- Launch the AppDynamics Agent Configuration utility and click Restart IIS on the Configuration Summary window.
Upgrade the .NET Agent from 3.7.8 through 3.8.6
Uninstall the Old Agent Version
Stop IIS, instrumented Windows services, and instrumented standalone applications.
If you shut down IIS but continue to see active IIS Worker Processes, check the Application Pools pane in the IIS Manager and stop any started application pools.
Failing to stop instrumented applications before uninstalling the .NET Agent may require you to reboot the machine.
- Stop the
AppDynamics.Agent.Coordinator
service. In the Control Panel, select Add/Remove Programs. Remove the
AppDynamics .NET Agent
.In some cases, another process interferes with the .NET Agent uninstallation process by locking the profiler.dll. If uninstallation fails, use a utility such as Process Explorer to see if a process is using profiler.dll. If so, terminate the process. Otherwise, try rebooting the machine. Then retry the uninstallation.
Install the New Agent Version
- Stop
w3wp
processes for instrumented IIS applications. Stop instrumented Windows services or standalone applications. - Download the MSI installer package from the AppDynamics Downloads.
- Launch an elevated command prompt with full administrator privileges. Logging on to Windows as a member of the Administrators group does not grant sufficient permissions to run the installer. See Start a Command Prompt as an Administrator.
- If you use a single-tenant Controller account, in the Controller click Settings > License > Account to view your access key.
Run a command-line agent install. For single-tenant Controller accounts, specify your account access key using the
AD_CONTROLLER_ACCOUNT_ACCESS_KEY
parameter. For example:msiexec /i "%USERPROFILE%\Downloads\dotNetAgentSetup.msi" /l log.txt /q AD_CONTROLLER_ACCOUNT_ACCESS_KEY=changeme
The installation runs silently in the background.
If you forget to add the account access key for a single-tenant Controller account, you can run the Agent Configuration Utility or manually add it to the config.xml later, see Account Element.
- Restart IIS:
- Launch the AppDynamics Agent Configuration utility and click Restart IIS on the Configuration Summary window.
or - Execute
iisreset
from the command line.
- Launch the AppDynamics Agent Configuration utility and click Restart IIS on the Configuration Summary window.
Upgrade the .NET Agent from <= 3.7.7
Identify the right upgrade path based upon the method of tier naming and assignment (manual or automatic) and the type of application you instrument:
- If you use manual tier naming and assignment, the installer package upgrades configurations for IIS applications and Windows services.
- If you used automatic tier naming and assignment, run the configuration utility to update configurations.
- If you used standalone applications with 3.7.7 or earlier, follow the steps for standalone applications on Configure the .NET Agent for Windows Services and Standalone Applications.
After installation, you may need to run the configuration utility to update your configuration and optionally remove legacy configurations.
Uninstall the Old.NET Agent Version
Stop IIS and instrumented Windows services.
If you shut down IIS but continue to see active IIS Worker Processes, check the Application Pools pane in the IIS Manager and stop any started application pools.
Failing to stop instrumented applications before uninstalling the .NET Agent may require you to reboot the machine.
- Stop the
AppDynamics.Agent.Coordinator
service. In the Control Panel, select Add/Remove Programs. Remove the
AppDynamics .NET Agent
.In some cases, another process interferes with the .NET Agent uninstallation process by locking the profiler.dll. If uninstallation fails, use a utility such as Process Explorer to see if a process is using profiler.dll. If so, terminate the process. Otherwise, try rebooting the machine. Then retry the uninstallation.
Install the New .NET AgentVersion
- Stop
w3wp
processes for instrumented IIS applications. Stop instrumented Windows services or standalone applications. - Download the MSI installer package from AppDynamics Downloads.
- Launch an elevated command prompt with full administrator privileges. Logging on to Windows as a member of the Administrators group does not grant sufficient permissions to run the installer. See Start a Command Prompt as an Administrator.
- Optional, if you use a single-tenant Controller account, in the Controller click Settings > License > Account to view your access key.
Run a command-line agent install. For single-tenant Controller accounts, specify your account access key using the
AD_CONTROLLER_ACCOUNT_ACCESS_KEY
parameter. For example:msiexec /i "%USERPROFILE%\Downloads\dotNetAgentSetup.msi" /l log.txt /q AD_CONTROLLER_ACCOUNT_ACCESS_KEY=changeme
The installation runs silently in the background.
If you forget to add the account access key for a single-tenant Controller account, you can run the Agent Configuration Utility or manually add it to the config.xml later, see Account Element.
- Restart IIS:
- Launch the AppDynamics Agent Configuration utility and click Restart IIS on the Configuration Summary window.
- Execute
iisreset
from the command line.
If you used the following environment variables with the earlier version, the MSI installer migrates the configurations to the new configuration file:
AppDynamicsAgent_CallGraphOptions
AppDynamicsAgent_DisableAppPools
AppDynamicsAgent_EnableInProcesses
AppDynamicsAgent_IgnoreCLREnv
AppDynamicsAgent_Profiler_Classes
Configure the .NET Agent
Configure the agent based on your method of tier generation and assignment: automatic or manual.
The .NET Agent configuration utility only supports the configuration of one Controller per server. To configure multiple business applications, see Configure Multiple Business Application Support for .NET
Configure the Agent Using Automatic Tier Generation and Assignment
If you used automatic configuration with the earlier version of the .NET Agent, run the configuration utility to configure the agent:
- Use the .NET Agent Configuration utility to reconfigure instrumentation for IIS applications. Choose Automatic for the method of tier generation and assignment. See Configure the .NET Agent.
- Configure instrumentation for Windows services manually. See Configure the .NET Agent for Windows Services and Standalone Applications.
Configure the Agent Using Manual Tier Generation and Assignment
For agents using manual tier generation and assignment, the installer package migrates the configurations for IIS applications and for Windows services to the config.xml
. At this stage, the configuration for IIS applications and Windows services is complete.
Clean Up Legacy Configurations
You can clean up legacy configurations by launching the AppDynamics Agent Configuration utility. When the utility detects agent settings from a previous version, it offers you the option to clean up.
The cleanup procedure modifies the web.config
files causing an IIS restart.
- Launch the AppDynamics Agent Configuration utility.
- Select Yes to clean up old AppDynamics configurations.
- Proceed through the wizard.
- Verify or update the log directory, and grant write permissions to it.
- Verify the controller connection information.
- Verify or update manual tier assignment.
The utility removes these configurations:
- AppDynamics configurations from
web.config
files for IIS applications andapplication.config
files for Windows services. - Environment variables:
AppDynamicsAgent_IgnoreCLREnv
AppDynamicsAgent_CallGraphOptions
AppDynamicsAgent_EnableInProcesses
AppDynamicsAgent_DisableAppPools
AppDynamicsAgent_Profiler_Classes
- AppDynamics configurations from
Resume Monitoring
Start IIS and instrumented Windows services.