This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.
« .NET Core and .NET 5+ Azure Functions »
Elastic Docs › ›Set up the Agent

ASP.NET

edit

ASP.NET

edit

Quick start

edit

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>

    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>

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

Our IIS module requires:

  • IIS 7 or later
  • Application pool’s pipeline mode has to be set to integrated (default for IIS 7 and up)
  • The deployed .NET application must NOT run under quirks mode. This makes LegacyAspNetSynchronizationContext the async context handler and can break HttpContext.Items correctly restoring when async code introduces a thread switch.

  1. 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.

« .NET Core and .NET 5+ Azure Functions »