setup-asp-dot-net.asciidoc

ASP.NET

Quick start

To enable auto instrumentation for ASP.NET (Full .NET Framework), you need to install the Elastic.Apm.AspNetFullFramework package, add a reference to the package in your web.config file, and then compile and deploy your application.

1. Ensure you have access to the application source code and install the Elastic.Apm.AspNetFullFramework package.

2. Reference the Elastic.Apm.AspNetFullFramework in your application’s web.config file by adding the ElasticApmModule IIS module:

   <?xml version="1.0" encoding="utf-8"?>
   <configuration>
       <system.webServer>
           <modules>
               <add name="ElasticApmModule" type="Elastic.Apm.AspNetFullFramework.ElasticApmModule, Elastic.Apm.AspNetFullFramework" />
           </modules>
       </system.webServer>
   </configuration>

   Note	There are two available configuration sources. To learn more, see [configuration-on-asp-net].

   By default, the agent creates transactions for all HTTP requests, including static content: .html pages, images, etc.

   To create transactions only for HTTP requests with dynamic content, such as .aspx pages, add the managedHandler preCondition to your web.config file:

   <?xml version="1.0" encoding="utf-8"?>
   <configuration>
       <system.webServer>
           <modules>
               <add name="ElasticApmModule" type="Elastic.Apm.AspNetFullFramework.ElasticApmModule, Elastic.Apm.AspNetFullFramework" preCondition="managedHandler" />
           </modules>
       </system.webServer>
   </configuration>

   Note	To learn more about adding modules, see the Microsoft docs.

3. Recompile your application and deploy it.

   The ElasticApmModule instantiates the APM agent on the first initialization. However, there may be some scenarios where you want to control the agent instantiation, such as configuring filters in the application start.

   To do so, the ElasticApmModule exposes a CreateAgentComponents() method that returns agent components configured to work with ASP.NET Full Framework, which can then instantiate the agent.

   For example, you can add transaction filters to the agent in the application start:

   public class MvcApplication : HttpApplication
   {
       protected void Application_Start()
       {
           // other application startup e.g. RouteConfig, etc.
   
           // set up agent with components
           var agentComponents = ElasticApmModule.CreateAgentComponents();
           Agent.Setup(agentComponents);
   
           // add transaction filter
           Agent.AddFilter((ITransaction t) =>
           {
               t.SetLabel("foo", "bar");
               return t;
           });
       }
   }

   Now, the ElasticApmModule will use the instantiated instance of the APM agent upon initialization.