Related pages:

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.

  1. Stop w3wp processes for instrumented IIS applications. Stop instrumented Windows services or standalone applications.
  2. Download the MSI installer package from AppDynamics Downloads. 
  3. 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.
  4. If you use a single-tenant Controller account, in the Controller click Settings > License > Account to view your access key.

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

  6. Restart IIS:
    • Launch the AppDynamics Agent Configuration utility and click Restart IIS on the Configuration Summary window.
      or
    • Execute iisreset from the command line.
    Restart Windows services and standalone applications.

Upgrade the .NET Agent from 3.7.8 through 3.8.6

Uninstall the Old Agent Version

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

  2. Stop the AppDynamics.Agent.Coordinator service.

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

  1. Stop w3wp processes for instrumented IIS applications. Stop instrumented Windows services or standalone applications.
  2. Download the MSI installer package from the AppDynamics Downloads.
  3. 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.
  4. If you use a single-tenant Controller account, in the Controller click Settings > License > Account to view your access key.

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

  6. Restart IIS:
    • Launch the AppDynamics Agent Configuration utility and click Restart IIS on the Configuration Summary window.
      or
    • Execute iisreset from the command line.
    Restart Windows services and standalone applications.

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

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

  2. Stop the AppDynamics.Agent.Coordinator service.

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

  1. Stop w3wp processes for instrumented IIS applications. Stop instrumented Windows services or standalone applications.
  2. Download the MSI installer package from AppDynamics Downloads.
  3. 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.
  4. Optional, if you use a single-tenant Controller account, in the Controller click Settings > License > Account to view your access key.

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

  6. Restart IIS:
    • Launch the AppDynamics Agent Configuration utility and click Restart IIS on the Configuration Summary window.
    • Execute iisreset from the command line.
    Restart Windows services.

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:

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

  1. Launch the AppDynamics Agent Configuration utility.
  2. Select Yes to clean up old AppDynamics configurations.
  3. 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 and application.config files for Windows services.
    • Environment variables:
      • AppDynamicsAgent_IgnoreCLREnv
      • AppDynamicsAgent_CallGraphOptions
      • AppDynamicsAgent_EnableInProcesses
      • AppDynamicsAgent_DisableAppPools
      • AppDynamicsAgent_Profiler_Classes

Resume Monitoring

Start IIS and instrumented Windows services.