On this page:

Related pages:

The MSI installer package for the new version of the AppDynamics .NET Agent installs updated agent files and maintains legacy configurations. When you upgrade from versions of the .NET Agent older than 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.

Requirements

  • Before you begin, review the Release Notes for changes that affect your environment.

  • AppDynamics requires an account access key for agent connections to single-tenant Controller accounts. Versions of AppDynamics before 4.1 only required an account access key for multi-tenant Controller accounts.

     

    Single-tenant Controller customers can find 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 Roles and Permissions.

     

    The .NET Agent only supports in-place upgrade for the following versions:

    • 3.9 or later.
    • 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 Version 3.9 or Newer

Except for patches to the current version, you do not need to uninstall the old agent first when you upgrade from the .NET Agent version 3.9 or later.

  1. Stop w3wp processes for instrumented IIS applications. Stop instrumented Windows services or standalone applications.
  2. Download the MSI installer package from the AppDynamics Download Center.
  3. Launch an elevated command prompt with full administrator privileges. See Start a Command Prompt as an Administrator. Logging on to Windows as a member of the Administrators group does not grant sufficient permissions to run the installer.
  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' on .NET Agent Configuration Properties.

  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 Versions 3.7.8 through 3.8.6

Uninstall the old version of the agent

  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 version of the agent

  1. Stop w3wp processes for instrumented IIS applications. Stop instrumented Windows services or standalone applications.
  2. Download the MSI installer package from the AppDynamics Download Center.
  3. Launch an elevated command prompt with full administrator privileges. See Start a Command Prompt as an Administrator. Logging on to Windows as a member of the Administrators group does not grant sufficient permissions to run the installer.
  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" on .NET Agent Configuration Properties.

  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 Version 3.7.7 or Earlier

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 version of the .NET Agent

  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 version of the .NET Agent

  1. Stop w3wp processes for instrumented IIS applications. Stop instrumented Windows services or standalone applications.
  2. Download the MSI installer package from the AppDynamics Download Center.
  3. Launch an elevated command prompt with full administrator privileges. See Start a Command Prompt as an Administrator. Logging on to Windows as a member of the Administrators group does not grant sufficient permissions to run the installer.
  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' on .NET Agent Configuration Properties.

  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 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. Answer Yes to clean up old AppDynamics configurations.
  3. Proceed through the wizard normally.
    • 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 the following configurations:

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