Dotnet Agent Installation with Remote Management - Powershell Extension

By:
thiru.chidambaram
AppDynamics supported
Updated June 1, 2017, 11:08 a.m.

Overview

The AppDynamics PowerShell module for .NET agent management provides a set of cmdlets to administrator AppDynamics .NET agents. It includes commands to manage agent inventory, versioning, deployment, and configuration. The script uses PowerShell remoting to manage agents on remote servers so you can use the module to administer agents locally or access remote agents in a datacenter.

Usage

To start using the library:

1. Download the module.

2. Unblock the file in Windows.

3. Launch Power Shell and import the module: Import-Module .\AppDynamics.psm1

4. While loading, the module checks for PowerShell version 3.0 or later and if the current user has administrative permissions. It issues a warning if there are problems.

5. Execute commands.

Requirements

PowerShell 3.0 or later
Windows 7/2003/2008/2008R2/2012/2012R2
Administrator level access for local machine management
Domain administrator access for remote agent management
Enable PowerShell remoting for Windows remote management (enabled by default starting Windows 2008 R2).

Common Command Options

Many of the cmdlets share the following options:

ComputerName: Specify a single remote host or a comma separated list of FQDN for remote hosts to execute the command.

For example:

ComputerName machine1.example.com, machine2.example.com, machine3.example.com

Alternatively provide the list of servers in a text file in the format ( Get-Content <path to text file> ).

For example:

ComputerName ( Get-Content .\Agents.txt )

RestartIIS: Restart IIS after installation or configuration change.

RestartWindowsServices: Specify a List of service names for services to restart.

For example:

RestartWindowsServices WindowsService1, WindowsService2, WindowsService3

RemoteShare: Change the location of shared directory on the remote machine where the script can copy installation files. The default value is c$\Temp\AppDynamics\Install\.

For example:

RemoteShare d$\temp\AppDynamics\

-RemotePath: Location of of source install and configuration files. For example:

-RemotePath d:\temp\AppDynamics\

Use cases

Take Agent Inventory

The Get-Agent cmdlet checks if the .NET Agent is installed and, if so, returns the version.

Syntax

Get-Agent

Examples

# Check agent inventory on the local machine.
Get-Agent

# Check agent inventory on multiple remote machines.
Get-Agent -ComputerName machine1.example.com, machine2.example.com, machine3.example.com

# Check agent inventory on a list of machines and export the results.
Get-Agent -ComputerName ( Get-Content .\servers.txt ) | Export-Csv .\Agents.txt

Deploy Agents

The Install-Agent cmdlet installs new agents locally or on remote servers. Optionally restart IIS or Windows services after installation, supply a template configuration, or copy bits to the remote servers from a central location. Once install completes, Install-Agent automatically starts the AppDynamics.Agent.Coordinator service.

See the bottom of this document for information on generating a template configuration file.

Syntax

Install-Agent <path to MSI installer> <path to configuration template>

Examples

#Install the agent locally with no configuration file.
Install-Agent .\dotNetAgentSetup-x64-3.9.5.0.msi

#Install the agent locally with a configuration file.
Install-Agent .\dotNetAgentSetup-x64-3.9.5.0.msi .\template.xml

#Install the agent on a single remote host.
Install-Agent .\dotNetAgentSetup-x64-3.9.5.0.msi .\template.xml -ComputerName machine1.example.com

#Install the agent on multiple remote servers and restart IIS.
Install-Agent .\dotNetAgentSetup-x64-3.9.5.0.msi .\template.xml -ComputerName ( Get-Content .\servers.txt ) -RestartIIS

#Install the agent on multiple remote servers. Restart IIS and and a list of Windows services.
Install-Agent .\dotNetAgentSetup-x64-3.9.5.0.msi .\template.xml -ComputerName ( Get-Content .\servers.txt ) -RestartIIS -RestartWindowsServices Service1, Service2, Service3

Deploy Agents Remote

When you install agents remotely, it is important to understand how the Install-Agent cmdlet copies the agent installation files to the remote machine(s):

When you begin the agent installer and template configuration are located on your local machine where your are running the PowerShell module or on a central shared repository location.
The Install-Agent cmdlet copies agent installation files to the default RemoteShare directory on the remote server(s):
c$\Temp\AppDynamics\Install\
When the script executes on the remote machine, it looks for the installation files at the default RemotePath directory:
c:\Temp\AppDynamics\Install\
Change the overrides using the -RemoteShare and -RemotePath command options. For example:

Example

#Install agents remotely. Restart IIS and a Windows Service. Change the location of the remote and local share paths.
Install-Agent .\dotNetAgentSetup-x64-3.9.5.0.msi .\template.xml -ComputerName ( Get-Content .\servers.txt ) -RestartIIS -RestartWindowsServices Service1 -RemoteShare d$\temp\AppDynamics\ -RemotePath d:\temp\AppDynamics\

Upgrade Agents

You can use the Install-Agent cmdlet to upgrade the agent. When Install-Agent finds an existing agent on the server, it uses the following logic:

Get the local agent version.
Compare the installed agent version to the version from the .msi file.
If the installed version is the same or newer - do nothing. Otherwise continue.
If -RestartIIS or -RestartWindowsServices parameters were passed - stop IIS and/or stop windows service(s).
Uninstall existing agent.
Check the return code - if there is a problem, stop and report the error code. Otherwise continue.
Install new agent.
If -RestartIIS or -RestartWindowsServices parameters were passed - start IIS and/or start windows service(s).
Start AppDynamics.Agent.Coordinator service.

It is very important to restart IIS and/or Windows services instrumented with the .NET Agent. Otherwise uninstall could fail due to locked agent files.

Modify Agent Configuration

The Update-Configuration cmdlet allows you to set the agent-controller connection. After you restart the instrumented application(s), either as part of the command or later, the new configuration takes effect and overrides any existing ones.

Syntax

Update-Configuration -Host <FQDN of Controller> -Port <Controller port> -SSL -Application <Controller business application> -AccountName <Controller account> -AccessKey <Controller access key>

See .NET Agent Configuration Properties for definitions of the command options.

Examples

#Configure connection to a single-tenant controller with SSL. Restart IIS.
Update-Configuration -Host "controller.example.com" -Port 443 -SSL -Application "Demo Application" -ComputerName machine1.example.com -RestartIIS

#Configure connection to a multi-tenant controller without SSL. Restart IIS and Windows services.
Update-Configuration -Host "controller.saas.example.com" -Port 80 -SSL:$false -Application "Demo Application" -AccountName "MyAccount" -AccessKey "secret$" -ComputerName ( Get-Content .\servers.txt ) -RestartIIS -RestartWindowsServices Service1, Service2, Service3

Modify Agent Configuration from Template

The Update-ConfigurationFromTemplate cmdlet applies a new configuration template to existing installed agents.

Once configuration is complete, Update-Configuration automatically restarts the AppDynamics.Agent.Coordinator service.

See the bottom of this document for information on generating a template configuration file.

Syntax

Update-ConfigurationFromTemplate <path to configuration template>

Examples

#Update agent config locally.
Update-ConfigurationFromTemplate .\template.xml

#Update agent configuration on a series of remote machines and restart IIS
Update-ConfigurationFromTemplate .\template.xml -ComputerName machine1.example.com, machine2.example.com, machine3.example.com

#Update agent configuration on a series of remote machines. Restart IIS and Windows Services
Update-ConfigurationFromTemplate .\template.xml -ComputerName ( Get-Content .\servers.txt ) -RestartIIS -RestartWindowsServices Service1, Service2, Service3

#Install agent configuration remotely. Restart IIS and a Windows Service. Change the location of the remote and local share paths.
Update-ConfigurationFromTemplate .\template.xml -ComputerName ( Get-Content .\servers.txt ) -RestartIIS -RestartWindowsServices Service1 -RemoteShare d$\temp\AppDynamics\ -RemotePath d:\temp\AppDynamics\

Uninstall the Agent

The Uninstall-Agent cmdlet uninstalls the .NET Agent from local or remote server(s) from the command line.

It is important to restart the monitored applications and/or services during the restart.

Syntax

Uninstall-Agent

Examples

#Uninstall the agent locally. Restart IIS
Uninstall-Agent -RestartIIS

#Uninstall the agent locally. Restart IIS and Windows services.
Uninstall-Agent -RestartIIS -RestartWindowsServices Service1, Service2

##Uninstall the agent remotely. Restart IIS and Windows services.
Uninstall-Agent -RestartIIS -RestartWindowsServices Service1, Service2 -ComputerName machine1.example.com, machine2.example.com

Restart the Agent Coordinator

Restart-Coordinator restarts AppDynamics.Agent.Coordinator windows service.

You don't have to use Restart-Coordiinator with the commands in this PowerShell module because the coordinator is internally restarted when required. This will be useful when you want to manually restart the Coordinator.

Syntax

Restart-Coordinator

Examples

#Restart the agent coordinator on multiple remote machines.

Restart-Coordinator -ComputerName machine1.example.com, machine2.example.com
Restart-Coordinator -ComputerName ( Get-Content .\servers.txt )

Read MSI File Version

The Get-MsiVersion cmdlet returns the version of a local msi installer package.

Syntax

Get-MsiVersion <path to MSI installer>

Advanced Options and Examples - Refer Attachment

Gotchas

How to prepare template configuration

Use the AppDynamics Agent Configuration utility to create a template configuration file. See Unattended Installation for .NET. Follow the steps to create a setup configuration file.
Manually configure the xml. See Unattended Installation for .NET for a sample file.

Don't use config.xml as template configuration. Installation will fail because the template configuration requires configuration properties in addition to the config.xml elements.

Uninstalling/upgrading agent problems - Troubleshooting Tips

The most common issue with uninstallation/upgrade is caused by monitored processes locking the agent files. When this happens PowerShell commands return only the generic messages from the Windows installer. For example: “Error 1603”.

How to approach this situation:

Access the target server.
Open the event viewer (eventvwr).
Examine events in the “Application” log around the time of the installation failure.
There should be multiple entries from the “MsiInstaller” source.
Find the one with which have error details.

Additionally grab the MSI log from the server, logs are %TEMP\AppDynamicsInstall.log and %TEMP\AppDynamicsUninstall.log
If you can’t identify the root cause and resolve the problem then contact AppDynamics support.

v 1.5.3 Update

-SharepointInstall

A new parameter “-SharepointInstall” is introduced for the commandlet “Install-Agent”. This sets the LoaderOptmization Registry key to 1 at the below locations. This setting is specific to address the sharepoint crashes when instrumented with Appdynamics.

HKLM:\SOFTWARE\Wow6432Node\Microsoft\.NETFramework 
HKLM:\SOFTWARE\Microsoft\.NETFramework

Usage

Install-Agent .\dotNetAgentSetup64.msi -SharePointInstall

Attachments: