Install the .NET Agent

The instructions in this section describe how to install a .NET agent on a Microsoft Internet Information Service (IIS) server.
apmdevops106
The instructions in this section describe how to install a .NET agent on a Microsoft Internet Information Service (IIS) server.
2
2
Before You Install
Review the deployment process.
Follow these steps:
  1. Verify that you have installed a supported version of these components:
    • .NET framework
      By default, the agent only monitors one Framework. You can configure agent properties to control what is monitored by using the .NET Framework 4 and In-Process Side-by-Side Execution.
    • Windows operating system and IIS
    • ODP.NET driver
  2. Verify that the web applications that you want to monitor run using the IIS worker process.
    1. Load a page from the application. 
    2. Open the Task Manager and look for these files on IIS:
      • aspnet_wp.exe
      • w3wp.exe
      If you see one of these files, you have completed the verification. Go to Step 4.
  3. Verify the applications that you want to monitor connect to one of these supported databases:
    • Microsoft SQL Server
    • Oracle database via ODP.NET
  4. If you do not see the worker process, enable IIS to handle managed components. 
    Navigate to the .NET Framework directory for the version of .NET you are using and run this command:
    aspnet_regiis.exe  -i
    For example:
    C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\aspnet_regiis.exe -i
  5. Verify that you have sufficient disk space available to install the agent files. We recommend that the disk space equals three times the size of the installer executable.
  6. Verify that any previous version of the .NET agent has been removed from the computer on which you intend to install a new .NET agent.
    You can verify whether the .NET agent is present by opening a command window and typing
    set
     to list the environment variables currently defined. When 
    com.wily.introscope.agentProfile=<path>
    is listed, remove the agent before proceeding.
  7. Verify that the computer where you intend to install the .NET agent does not have another monitoring agent or CLR profiler installed.
  8. Verify that you have installed the Enterprise Manager and Workstation. Note the host name and port number for configuring the Enterprise Manager connection.
    Use
    ping
    or Telnet to verify connectivity between the agent and the Enterprise Manager.
Select the Installation Method
You can install the .NET agent using one of these methods:
3
3
Usually you use the interactive installer when you want to install files locally on a computer. However, you can run the installer in a script with command line parameters in some situations. For example, when you want to install files remotely on a computer or to deploy a preconfigured set of installation instructions. When you do not want to run the installer interactively or silently, you can manually install and configure the agent using an installation archive.
For either installation method, the Windows Active Directory domain user account that is chosen for SharePoint monitoring requires Log on as Service privileges.
Install the .NET Agent Interactively
You can install the .NET agent interactively by starting the .NET agent installer program and responding to the prompts displayed.
Follow these steps:
  1. Double-click the agent installer executable for 32-bit or 64-bit operating system.
    For example, double-click a file with a name similar to this executable:
    introscope<version>windowsAgent_dotNET_32.exe
    The Welcome page appears. Select
    Next
    to start the installation.
    You can install using either the
    .exe
    or
    .msi
    executable. The 
    .msi
    executable provides enabling software delivery by group policy or other automated delivery, such as a scheduled task. The
    .exe
    executable provides more functionality. For example, you can right-click to run the installer as an administrator when you are not logged on as an administrator.
  2. Select
    Next
    to accept the default installation directory or select
    Change
    to select another directory, then select
    Next
    .
    The default installation directory for the .NET agent is C:\Program Files\CA APM\Introscope
    <
    version
    >
    Within the root installation directory, the installer creates the
    wily
    directory that is the default 
    <
    Agent_Home
    >
    directory.
  3. Type the host name and port number for the Enterprise Manager to which the agent should report metrics, then select
    Next
    .
    The default Enterprise Manager for the agent is
    localhost
    . Local host is appropriate in a lab environment where the Enterprise Manager and agent are installed on the same computer. In a typical production environment, configure the connection to a remote Enterprise Manager. The default Enterprise Manager port is
    5001
    .
  4. Select the monitoring options that you want to enable, then select
    Next
    .
    When you do not enable any monitoring options, you can manually enable monitoring options later.
  5. Select whether more agent services should be started automatically or manually.
    When you select CA APM Standalone Agent for Microsoft SharePoint (SPMonitor)
    Specify a Windows Active Directory domain user account and password for the service to run as.
    Example: 
    <domain>\<username>
  6. Select
    Install
    .
    The installer creates the .NET agent root installation directory and installs the files that the agent uses.
  7. When the installation is complete, select
    Finish
    .
  8. To verify that the agent has been installed successfully, perform 
    one
    of these verifications:
    • .exe installer
      Verify that the
      IntroscopeDotNetAgentInstall*.exe.log file is in the same directory as the installer executable.
    • .msi installer
      Verify that the MSI*.LOG file is created under the
      %temp%
      directory. The log file is only available for Windows Installer 4.0 minimum.
  9. Restart the IIS Admin Service to complete the installation.
Installing the .NET agent adds these system environment variables to the operating system:
com.wily.introscope.agentProfile
,
Cor_Enable_Profiling
,
COR_PROFILER
. Restarting IIS or rebooting the local computer is required to inform IIS that system environment variables have changed.
Install .NET Agent Silently
To run the installer in silent mode, invoke the .NET agent installer from a command line and specify the installation instructions as command line parameters. The installation then runs in the background without displaying any information about its progress. Because this installation method enables you to install the agent without user interaction, it is most commonly used to install .NET agents on remote computers. You can also install multiple agents with the same configuration. You can specify either the .exe or .msi executable on the command.
Follow these steps:
  1. Open a Command Prompt window.
    Invoke the appropriate
    .exe
    or
    .msi
    installer executable with the appropriate command line parameters.
    For example, to install on a 64-bit system you can use these command line parameters. 
    Format the version number as x.x.x.x.
    .msi
    installer:
    IntroscopeDotNetAgentInstall64_<version>.msi /qn [INSTALLDIR="<install_dir>"] [EMHOST=myhost] [EMPORT=5001] [ENABLECD=1 CDAGENTID=<change_dectector_agent_id>] [ENABLESPP=1] [INSTALLSPMONITOR=1 IS_NET_API_LOGON_USERNAME=<SP Monitor Domain username> IS_NET_API_LOGON_PASSWORD=<SP Monitor Domain password>]
    .exe
    installer:
    IntroscopeDotNetAgentInstall64_<version>.exe /s /v"/qn [INSTALLDIR="<install_dir>"] [EMHOST=myhost] [EMPORT=5001] [ENABLECD=1 CDAGENTID=<change_dectector_agent_id>] [ENABLESPP=1] [INSTALLSPMONITOR=1] IS_NET_API_LOGON_USERNAME=<SP Monitor Domain username> IS_NET_API_LOGON_PASSWORD=<SP Monitor Domain password>]"
    You invoke the installer with the
    /s
    /v
    /q
    n
    options to install silently. Specifying the other parameters is optional. When you do not specify a parameter on the command line, the installer uses the parameter default setting. These optional parameters are equivalent to the selections you make when running the installer interactively:
    INSTALLDIR=<root_installation_directory>
    Specifies the directory for installing the .NET agent. When the path includes a backslash, you add a preceding backslash to the path. For example:
    \C:\IntroscopeDir
    The default root installation directory is:
    C:\Program Files\CA APM\Introscope<version>
    Modify this property when you want to change the default directory.
    EMHOST=<host_name>
    Specifies the host name for the Enterprise Manager to which the agent reports metrics. The default host name for the agent is localhost.
    EMPORT=<port_number>
    Specifies the listening port number for the Enterprise Manager to which the agent reports metrics. The default port is 5001
    .
    ENABLECD=0
    Specifies whether to enable ChangeDetector. The default value for this parameter is 0, indicating that ChangeDetector must not be enabled.
    When you want to enable ChangeDetector, set the
    ENABLECD
    parameter to
    1
    .
    When you leave ChangeDetector disabled, the related files are placed in the <Agent_Home>\examples directory and can be enabled later.
    CDAGENTID=<agent_name>
    Specifies a name for the ChangeDetector agent. Only include this parameter on the command line when you set
    ENABLECD
    to
    1
    . The default agent name for the ChangeDetector agent is SampleApplicationName.
    ENABLESPP=0
    Specifies whether to enable CA APM for Microsoft SharePoint Portal. The default value for this parameter is 0, indicating that CA APM for Microsoft SharePoint must not be enabled.
    When you want to enable CA APM for Microsoft SharePoint Portal, set the
    ENABLESPP
    parameter to
    1
    . Only enable monitoring for Microsoft SharePoint when the operating system is Windows Server 2003 or Windows Server 2008.
    When you leave CA APM for Microsoft SharePoint Portal disabled, the related files are placed in the
    <
    Agent_Home
    >
    \examples directory and can be enabled later.
    INSTALLSPMONITOR=0
    Specifies whether to install the CA APM Standalone Agent for Microsoft SharePoint Portal. The default value for this parameter is 0, indicating that CA APM Standalone Agent for Microsoft SharePoint must not be installed.
    When you want to install the CA APM Standalone Agent for Microsoft SharePoint, set the
    INSTALLSPMONITOR
    parameter to
    1
    .
    If you do not install the CA APM Standalone Agent for Microsoft SharePoint, you can install it later. You can run the CA APM Standalone Agent installer.
    For example, to change the default settings on a 64-bit system, specify a command line similar to this example:
    IntroscopeDotNetAgentInstall64_<version>.exe /s /v"/qn INSTALLDIR=\"C:\IntroscopeAgent\" EMHOST=dell-M65.org EMPORT=5001 ENABLECD=1 CDAGENTID=myCDAgent ENABLESPP=1 INSTALLSPMONITOR=1 IS_NET_API_LOGON_USERNAME=apm-domain\apmuser IS_NET_API_LOGON_PASSWORD=apmPassword"
    • IS_NET_API_LOGON_USERNAME=
      <
      domain>
      \
      <username>
      Specifies the Microsoft SharePoint monitor domain user name. This parameter is provided when the
      INSTALLMONITOR
      parameter is set to
      0
      . The default value for this parameter is null.
    • IS_NET_API_LOGON_PASSWORD=<password>
      Specifies the password for the Microsoft SharePoint monitor. The default value for this parameter is null.
  2. To verify that the agent has been installed successfully, view the log file as follows:
    • .exe
      installer:
      View the IntroscopeDotNetAgentInstall*.exe.log file in the same directory as the installer executable.
    • .msi
      installer:
      View the MSI*.LOG file in the
      %temp%
      directory. The log file is only available for Windows Installer 4.0 minimum.
  3. (Optional) Create a script that invokes the installer with the appropriate settings. The script can invoke settings for installation as scheduled task or to run remotely on more computers.
  4. Restart IIS Admin Service to complete the installation.
Installing the .NET agent adds these system environment variables to the operating system:
com.wily.introscope.agentProfile
,
Cor_Enable_Profiling
, and
COR_PROFILER
. Restarting IIS or rebooting the local computer is required to inform IIS that system environment variables have changed.
Install the .NET Agent Manually Using Installation Archives
You can include the agent files on a system without running the installer interactively or configuring a response file. Application server-specific archives let you install the agent.
Installation archives contain the same files for the agent installer. After you copy an archive to a computer, extract the contents and configure the agent. Use these files for deploying multiple agents in a batch job, or keeping the files as an archive of the default set of agent files.
Follow these steps:
  1. Download
    one
    of the following installation archives from the CA Support CA APM software download area:
    • DotNetAgentFiles-NoInstaller.x64.<version>.zip
    • DotNetAgentFiles-NoInstaller.x86.<version>.zip
    For example:
    DotNetAgentFiles-NoInstaller.x64.<version>.zip
  2. Extract the installation archive contents into a directory of your selection.
  3. Set up the
    <
    Agent_Home
    >
     directory for the .NET agent. The default root installation directory is C:\Program Files\CA APM\Introscope
    <
    version
    >
    . From the root installation directory, the installer creates the wily directory, which is the default
    <
    Agent_Home
    >
    directory.
  4. At a command prompt, run the gacutil.exe in the Windows SDK to register the wily.Agent.dll
     
    file to the Global Assembly Cache. The wily.Agent.dll is located in the <Agent_Home>\bin directory. For example:
     gacutil -i <Agent_home>\bin\wily.Agent.dll
  5. Register the wily.NativeProfiler file as follows:
    1. From a command line, navigate to the
      <
      Agent_Home
      >\
      bin directory and invoke this executable:
      C:\WINDOWS\SysWOW64\regsvr32.exe <Agent_Home>\bin\x86\wily.NativeProfiler.dll
  6. Open the IntroscopeAgent.profile file in a text editor and configure the Enterprise Manager connection as follows:
    1. Locate the line:
      introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT
      , and specify the host name of the Enterprise Manager for the agent. For example:
      introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=sfcollect01
    2. Set other properties for communication with the Enterprise Manager as appropriate.
  7. Start the PerfMon Collector Service from a command line as follows:
    sc create PerfMonCollectorAgent binPath= "<Agent_home>\bin\PerfMonCollectorAgent.exe start= auto DisplayName= "CA APM PerfMon Collector Service"
  8. To verify that users have permission to access the
    <
    Agent_Home
    >
    directory, run the
    wilypermissions
    utility from a command line. For example:
    wilypermissions.exe c:\WilyAgent9065\wily w3wp.exe
  9. Configure these .NET agent environment variables:
    • com.wily.introscope.agentProfile=<Agent_Home>\IntroscopeAgent.profile
    • Cor_Enable_Profiling=0x1
    • COR_PROFILER={5F048FC6-251C-4684-8CCA-76047B02AC98}
  10. To complete the installation, restart the IIS Admin Service.
Install the .NET Agent in Chinese or Japanese
You can specify a language value when you run the .msi installer executable.
This information applies to 32- and 64-bit Windows only.
Follow these steps:
  1. Open a Command Prompt window.
  2. Invoke the .msi installer executable with the language value as follows:
    • Japanese:
      IntroscopeDotNetAgentInstall64_<version>.msi TRANSFORMS=1041.mst ProductLanguage=1041
    • Chinese:
      IntroscopeDotNetAgentInstall64_<version>.msi TRANSFORMS=2052.mst ProductLanguage=2052
  3. To complete the installation, restart the application server.
    The installer creates the .NET agent root installation directory and installs the agent files. The installer creates the.MSI*.LOG file in the
    %temp%
    directory.
Verify the .NET Agent Installation
Sometimes, you cannot know whether the .NET agent has been installed or disabled on a particular computer. You can be unaware of installation or configuration errors. You can perform environment checks when you are unsure whether the .NET agent is installed. You can also perform the checks when you want to verify that the .NET agent is properly configured.
Follow these steps:
  1. Confirm the .NET agent environment variables are set and have the correct values.
    Open a Command window, type
    set
    and direct the output to a text file. Review the file to verify that these environment variables are set:
    com.wily.introscope.agentProfile=C:\Program Files\CA Wily\Introscope<version>\wily\IntroscopeAgent.profile
    Cor_Enable_Profiling=0x1
    COR_PROFILER={5F048FC6-251C-4684-8CCA-76047B02AC98}
  2. Verify that the correct version of wily.Agent.dll is registered in the Global Assembly Cache (c:\windows\assembly).
    When wily.Agent.dll is not listed, as the administrator, copy <Agent_Home>\bin\wily.Agent.dll into C:\Windows\assembly.
  3. Examine the user account that runs the IIS worker process. Verify that all accounts that the worker process runs under have Full Control permissions on the
    <
    Agent_Home
    >
    directory.
Remove the .NET Agent
To remove the .NET agent for your operating system, use
one
of these methods:
4
4
Note
: Use the uninstall program for your operating system. For example, When you use the .exe installer program, then use the corresponding .exe uninstaller program to remove the agent. Otherwise, the process cannot remove the agent.
Remove the .NET Agent Interactively
The .NET agent is active whenever an instrumented application is running. Before you can delete or modify any agent DLL files, ensure that all instrumented applications are stopped. You can then remove agent files locally using the Add or Remove Programs Control Panel or silently using the uninstall program.
Follow these steps:
  1. Stop the IIS service.
    This action stops all instrumented applications.
  2. Navigate to
    Start
    ,
    Settings
    ,
    Control Panel
    ,
    Add or Remove Programs
    .
  3. Select
    one
    of these programs from the list of currently installed programs:
    • CA APM .NET Agent<version> (32 bit)
    • CA APM .NET Agent<version> (64 bit)
  4. Select
    Remove
    .
    You are prompted to confirm that you want to remove the agent.
  5. Select
    Yes
    to remove the agent.
    The .NET agent DLLs are unregistered, related environment variables are removed, and the agent files are removed.
  6. Close
    Add or Remove Programs
    .
  7. Restart the IIS Admin Service or reboot the computer.
  8. Select the root installation directory for the agent, right-click, and then select
    Delete
    .
    The .NET agent is removed.
Remove the .NET Agent in Silent Mode
You can remove the .NET agent and associated files in silent mode.
Follow these steps:
  1. Stop the IIS service to stop all instrumented applications.
  2. Run
    one
    of these commands at the command prompt:
    IntroscopeDotNetAgentInstall64_<version>.exe /s /x /v"qn"
    IntroscopeDotNetAgentInstall64_<version>.msi /x /qn
    The .NET agent is removed.
Remove the .NET Agent Manually
You can remove the .NET agent and associated files manually.
The .NET agent is active whenever an instrumented application is running. Before you can delete or modify any agent DLL files, ensure that all instrumented applications are stopped.
Follow these steps:
  1. Navigate to the C:\WINDOWS\assembly directory.
  2. Right-click
    wily.Agent.dll
    and select
    Uninstall
    from the menu.
    The agent files are removed.
  3. Open a command prompt as the administrator.
    1. Remove the NativeProfiler file by typing these commands:
      • C:\WINDOWS\system32\regsvr32.exe /u <Agent_Home>\bin \wily.NativeProfiler.dll
      • C:\WINDOWS\SysWOW64\regsvr32.exe /u <Agent_Home>\bin\x86 \wily.NativeProfiler.dll
    2. Remove the PerfMon Collector Service by running this command:
      sc delete PerfMonCollectorAgent
    3. Manually remove these .NET agent environment variables:
      • com.wily.introscope.agentProfile=<Agent_Home>\IntroscopeAgent.profile
      • Cor_Enable_Profiling=0x1
      • COR_PROFILER={5F048FC6-251C-4684-8CCA-76047B02AC98}
  4. Restart the IIS to complete the uninstall process.