Configure the App Agent for .NET properties using a single configuration file. This topic describes the structure and content of the config.xml file to help you customize agent behavior. To use the .NET Agent Configuration Utility, see Configure the App Agent for .NET.

Overview

The App Agent for .NET uses a single configuration file to control agent behavior: Controller connectivity, machine agent operations, and app agent functionality for IIS applications, Windows services, and standalone applications such as console applications, WinForms, or WPF. Benefits of the unified configuration file include:

• Maintain agent configurations separately from web.config files.
• Enable instrumentation of Windows services and standalone applications without environment variables.
• Control agent behavior for specific applications with hierarchical configuration.

To configure connection to the Controller, See Controller Element.

To configure the .NET machine agent, See Machine Agent Element.

To configure app agents for IIS applications, see App Agents - IIS Element.

To configure an app agent for a Windows service, see App Agents - Windows Services Element.

To configure an app agent for a standalone application, see App Agents - Standalone Applications Element.

Where to Configure App Agent Properties

%ProgramData%\AppDynamics\DotNetAgent\Config\config.xml

%AllUsersProfile%\Application Data\AppDynamics\DotNetAgent\Config\config.xml

Sample config.xml files install to the following location:

%ProgramFiles%\AppDynamics\AppDynamics .NET Agent\SampleConfigurations

 After you edit the config.xml, you must restart the AppDynamics.Agent.Coordinator service. Then restart IIS, your Windows service, or standalone application for your instrumentation changes to take effect.

Minimal .NET App Agent controller-info.xml File

The most basic configuration demonstrates the required sections for agent configuration. This sample instruments all IIS applications using the automatic element (<automatic />). No Windows services or standalone applications are instrumented.

<?xml version="1.0" encoding="utf-8"?>
<appdynamics-agent xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <controller host="mycontroller.mycompany.com" port="8090" ssl=false">
    <application name="MyDotNetApplication" />
  </controller>
  <machine-agent />
  <app-agents>
    <IIS>
      <automatic />
    </IIS>
  </app-agents>
</appdynamics-agent>

AppDynamics Agent Element

The Appdyanmics Agent element is the root container element for configurations in the config.xml.

Required Element: <appdynamics-agent xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

Controller Element

The Controller element is a child of the AppDynamics Agent element. It specifies the connection information for the AppDyanmics Pro Controller.

The App Agent for .NET only supports configuration of one Controller per server.

Required Element: <controller host="mycontroller.mycompany.com" port="8090" ssl="false">

Controller host attribute

The Controller host attribute indicates the host name or the IP address of the AppDynamics Controller. For an on-premise Controller, use the value for Application Server Host Name you provided when you installed the Controller. If you use the AppDynamics SaaS Controller, see the Welcome email from AppDynamics.

Type: String
Default: None
Required: Yes

Controller port attribute

The Controller port attribute specifies the HTTP(S) port of the AppDynamics Controller. If the Controller ssl attribute is set to true, specify the HTTPS port of the Controller; otherwise specify the HTTP port.

Type: Positive Integer
Default: 8090

For On-premise installations, the defaults are port 8090 for HTTP and port 8181 for HTTPS.

For the SaaS Controller, use port 80 for HTTP or port 443 for HTTPS.

Required: Yes

Controller ssl attribute

To enable encryption over SSL between the agent and the Controller, set the Controller ssl attribute to "true".

Type: Boolean
Default: false
Required: No

Controller Application Element

The Controller Application element is a child of the Controller element. It indicates the name of the logical business application you see in the Controller interface.

The .NET Agent configuration utility only supports configuration of one business application per server.

• Use tiers to organize different applications you instrument on a single server.
• Or manually configure support for multiple business applications, see Configure Multiple Business Application Support for .NET.

Required Element: <application name="MyDotNetApplication"/>

Application name attribute

Set the application name attribute to the business application you use in the controller. If the application name does not exist, the Controller will create it when the agent registers. All instrumented applications in the config.xml register with the same business application in the Controller. See Logical Model.

Type: String
Default: None
Required: Yes

You specify a Tier for individual applications in the App Agents Element.

Account Element

The Account element is a child of the Controller element. If the AppDynamics Controller runs in multi-tenant mode or if you use the AppDynamics SaaS Controller, specify the account name and account access key for the agent to authenticate with the Controller. If you are using the AppDynamics SaaS Controller, the account name is provided in the Welcome email from AppDynamics.

Optional Element: <account name="mycontroller.saas.appdynamics.com" password="myaccesskey"/>

Account name attribute

The account name attribute indicates to the account name for the SaaS or multi-tenant Controller.

Type: String
Default: None
Required: Only for SaaS or multi-tenant Controllers

Account password attribute

The account password attribute indicates the access key for the SaaS or multi-tenant Controller.

Type: String
Default: None
Required: Only for SaaS or multi-tenant Controllers

Proxy Element

The Proxy element is a child of the Controller element. Use it to configure connection to the Controller through a proxy server with no authentication.

Optional Element: <proxy host="proxy-name" port="3128" enabled="true"/>

Proxy host attribute

The proxy host attribute indicates the proxy server host name or IP address.

Type: String
Default: None
Required: host is required for the proxy element

Proxy port attribute

The proxy port attribute indicates the proxy server port.

Type: Positive Integer
Default: None
Required: port is required for the proxy element

Proxy enabled attribute

To enable Controller access through a proxy server, set the proxy enabled attribute to "true".

Type: Boolean
Default: false
Required: No

Machine Agent Element

The Machine Agent element is a child of the AppDynamics Agent element. An empty Machine Agent element enables the default instrumentation for the .NET machine agent (See Monitor CLRs and Monitor IIS). Enable optional additional Microsoft Performance Counters or App Agent for .NET instrumentors as children of the Machine Agent element.

Required Element: <machine-agent/>

Performance Counters Element

The Performance Counters element is a child of the Machine Agent element. It is a container for all performance counters.

Optional Element: <perf-counters>

Performance Counter element

The Performance Counter element is a child of the Performance Counters element. For a list of performance counters to enable, see Performance Counters in the .NET Framework.

Optional Element: <perf-counter cat="category" name="name" instance="instance"/>

Performance Counter cat attribute

The performance counter cat attribute indicates the performance counter category.

Type: String
Default: None
Required: Category is required for the Performance Counter element.

Performance Counter name attribute

The performance counter name attribute indicates the performance counter name.

Type: String
Default: None
Required: Name is required for the Performance Counter element.

Performance Counter instance attribute

The performance counter instance attribute is the performance counter instance value.

Type: String
Default: None
Required: Instance is required for the Performance Counter element.

Sample Machine Agent Configuration with Performance Counters

  <machine-agent>
    <!-- Additional machine level Performance Counters -->
    <perf-counters>
      <perf-counter cat="Network Interface" name="Bytes Sent" instance="Local Area Connection"/>
    </perf-counters>
  </machine-agent>

Instrumentation Element

The Instrumentation element is a child of the Machine Agent element. It allows you to enable additional App Agent for .NET instrumetors such as thread correlation or correlation for .NET remoting.

Optional Element: <instrumentation>

Instrumentor element

The Instrumentor element is a child of the Instrumentation element. The instrumentor element specifies the App Agent for .NET instrumentor to implement.

Optional Element: <instrumentor name="instrumentor name" enabled="true"/>/>

Instrumentor name attribute

The instrumentor name attribute indicates the instrumentor name.

Type: String
Default: None
Required: Name is required for the Instrumentor element.

Instrumentor enabled attribute

Set the instrumentor enabled attribute to "true" to enable instrumentation.

Type: Boolean
Default: false
Required: No.

The current configuration syntax is enabled="true". Versions prior to 3.7.8 used disabled="false".

Sample Machine Agent Configuration with Thread Correlation Instrumentors

 <machine-agent>
    <!--Enable thread correlation-->
    <instrumentation>
        <instrumentor name="ThreadCorrelationThreadPoolCLR2Instrumentor" enabled="true"/>
        <instrumentor name="ThreadCorrelationThreadPoolCLR4Instrumentor" enabled="true"/>
        <instrumentor name="ThreadStartCLR2Instrumentor" enabled="true"/>
        <instrumentor name="ThreadStartCLR4Instrumentor" enabled="true"/>
    </instrumentation>
  </machine-agent>

Additional App Agent for .NET Instrumetors

• See Enable Thread Correlation for .NET.
• See Enable Correlation for .NET Remoting.
• See Enable Instrumentation for WCF Data Services.

App Agents Element

The App Agents element is a child of the AppDynamics Agent element. It is a container for app agent configurations for IIS applications, Windows services, and standalone applications.

Required Element: <app-agents enabled="true">

App agents enabled attribute

To disable application monitoring on the server, set the app agents enabled attribute to "false".

Type: Boolean
Default: true
Required: No

App Agents - IIS Element

The IIS element is a child of the App Agents element. There are three options to configure IIS applications:

• Automatic configuration
• Application pool configuration
• Application configuration

The settings for any application pool apply to all applications within the app pool unless the individual application has a specific configuration.

Explicit child-level configurations override parent-level configurations. Otherwise, children inherit parent configurations.

Optional Element: <IIS>

IIS Automatic Instrumentation Element

The Automatic element is a child of the IIS element. Use the Automatic element to enable or disable automatic instrumentation for all IIS apps. You can configure automatic instrumentation and manual instrumentation both. Manual configurations override automatic ones.

Optional Element: <automatic enabled="false" />

Automatic enabled attribute

Set the automatic enabled attribute to "true" to enable instrumentation for all IIS applications. This is the default setting if you use the .NET Agent Configuration Utility automatic configuration option. To disable automatic instrumentation for all IIS applications, set the value to "false".

Type: Boolean
Default: true
Required: No

IIS Application Pools Element

The IIS Application Pools element is a child of the IIS element. It is a container element for all the IIS application pools you configure for instrumentation.
Optional Element: <application-pools>

IIS Application Pool Element

The Application Pool element is a child of the Application Pools element.. You may have multiple application pool elements distinguished by the name attribute. Use the application pool element to configure the app agent for all applications within an application pool. For more information on IIS application pools, see Managing Application Pools in IIS.

Application-specific configurations in the IIS Applications element override application pool configurations.

Optional Element: <application-pool name="DefaultAppPool" enabled="false">

Application pool name attribute

The application pool name attribute indicates the name of the IIS Application Pool.

Type: String
Default: None
Required: Name is required for the Application Pool element.

Application pool enabled attribute

Set the application pool enabled attribute to "false" to disable instrumentation for all applications in the application pool. Set the value to "true" to instrument all applications in the application pool.

Type: Boolean
Default: None. Defaults to true if not specified.
Required: No

Application Pool Tier Element

The Tier element is a child of the Application Pool element. If you enable instrumentation for an Application pool, you must use a Tier element to assign the pool's applications to a tier in the Controller. See Logical Model.

Required Element: <tier name="Inventory" />

Tier name attribute

Use the tier name attribute to specify the tier.

Type: String
Default: None
Required: Yes

IIS Applications Element

The IIS Applications element is a child of the IIS element. It is a container element for all the IIS applications you configure for instrumentation.
Optional Element: <applications>

Application Element

The Application element is a child of the Applications element. Use multiple application elements to instrument different sites and applications. To learn more about IIS sites and applications, see Understanding Sites, Applications, and Virtual Directories on IIS 7 and Above.

Optional Element: <application path="/" site="FirstSite" port="8008">

Application site attribute

The application site attribute indicates the root site in IIS for the application.

Type: String
Default: None
Required: Site is required for the Application element.

Application path attribute

The application path attribute indicates the application's path relative to the root site. Use the forward slash to indicate the root site and instrument all children applications. Use the path to an application to instrument the specific application and any children.

For example: Site1 hosts two applications AppX and AppY. To instrument Site 1, AppY and AppZ, set the path to "/". To instrument AppY, but not AppZ, set the path to "/AppY".

Type: String
Default: /
Required: Path is required for the Application element.

Application port attribute

For cases where two or more sites in IIS 6 have the same site name, set the site port attribute to differentiate between the sites.

Type: Positive Integer
Default: None
Required: No

Application enabled attribute

In certain cases you may want to enable instrumentation for a parent application, but disable it for a child application. In this case create an Application element for the child application to disable and set the application enabled attribute to to "false".

Type: Boolean
Default: true
Required: No

Application Tier Element

The Tier element is a child of the Application element. If you enable instrumentation for an application, your must use a Tier element to assign the application to a tier in the Controller. See Logical Model.

Required Element: <tier name="Consumer" />

Tier name attribute

The tier name attribute indicates the business application tier.

Type: String
Default: None
Required: Yes

Sample IIS Application Configuration

    <IIS>
      <!-- Automatic instruments all IIS applications when enabled -->
      <automatic enabled="false" />

      <!-- Application Pool agent configurations -->
      <application-pools>
        <!-- Do not instrument applications in DefaultAppPool when "enabled" attribute is set to false -->
        <application-pool name="DefaultAppPool" enabled="false">
          <tier name="Tier Name"/>
        </application-pool>

        <!-- Instrument applications in the OtherAppPpool and assign them to the Inventory tier -->
        <application-pool name="OtherAppPool">
          <tier name="Inventory"/>
        </application-pool>
      </application-pools>

      <applications>
        <!-- Instrument all applications in the First Site -->
        <application path="/" site="FirstSite">
          <tier name="Order"/>
        </application>
        <!-- Instrument the /app application and child apps in the Second Site -->
        <!-- but not the root Second Site application -->
        <application path="/app" site="SecondSite">
          <tier name="Consumer"/>
        </application>
      </applications>
    </IIS>

App Agents - Windows Services Element

The Windows Services element is a child of the App Agents element. It is a container element for all the Windows Services you configure for instrumentation.

For instructions to instrument Windows services, see Enable the App Agent for .NET for Windows Services.

Optional Element: <windows-services>

Windows Service Element

The Windows Service element is a child of the Windows Services element. It specifies a Windows service to instrument.

Optional Element: <windows-service name="MyWindowsService">

Service name attribute

The service name attribute indicates the service name for the Windows service to instrument.
Use the value of the Service name from the service properties window. Do not use the Display name.

Type: String
Default: None
Required: Yes

Service app-domain-name attribute

For applications with multiple application domains, the app-domain-name attribute enables you to limit instrumentation to specific application domains. See Configure Application Domain Monitoring.

Type: String
Default: None
Required: No

Windows Service Tier Element

The Tier element is a child of the Windows Service element. If you enable instrumentation for an application, your must use a Tier element to assign the application to a tier in the Controller. See Logical Model.

Required Element: <tier name="Consumer" />

Tier name attribute

The tier name attribute indicates the business application tier.

Type: String
Default: None
Required: Yes

Sample Windows Service Configuration

    <windows-services>
      <windows-service name="MyWindowsService">
        <tier name="Service Tier"/>
      </windows-service>
    </windows-services>

App Agents - Standalone Applications Element

The Standalone Applications element is a child of the App Agents element. It is a container element for all the standalone applications you configure for instrumentation.

For instructions to instrument standalone applications, see Enable the App Agent for .NET for Standalone Applications.

Optional Element: <standalone-applications>

Standalone Application Element

The Standalone Application element is a child of the Standalone Applications element. It specifies a standalone application to instrument.

Optional Element: <standalone-application executable="MyWindowsApplication.exe">

Standalone Application executable attribute

The standalone application executable attribute specifies the file name of the Windows application to instrument.

Only use the application file name. Do not include the full path to the file. For example, if you want to instrument, C:\Program Files\My Application\MyApp.exe, the executable value is "MyApp.exe". The file extension is optional, so "MyApp" also works.

Type: String
Default: None
Required: Yes

Standalone application app-domain-name attribute

For applications with multiple application domains, the app-domain-name attribute enables you to limit instrumentation to specific application domains. See Configure Application Domain Monitoring.

Type: String
Default: None
Required: No

Standalone Application Tier Element

The Tier element is a child of the Standalone Application element. If you enable instrumentation for an application, your must use a Tier element to assign the application to a tier in the Controller. See Logical Model.

Required Element: <tier name="Consumer" />

Tier name attribute

The tier name attribute indicates the business application tier.

Type: String
Default: None
Required: Yes

Sample Standalone Application Configuration

    <standalone-applications>
      <standalone-application executable="MyWindowsApplication.exe">
        <tier name="StandaloneApplication Tier"/>
      </standalone-application>
    </standalone-applications>

Learn More

• Logical Model
• Name Business Applications, Tiers, and Nodes
• Configure the App Agent for .NET
• Enable the App Agent for .NET for Windows Services
• Enable the App Agent for .NET for Standalone Applications