Chat Support
Loupe - Log - Monitor - Resolve
Loupe / Getting Started / .NET Core / 6 / 8 / Using Loupe with ASP.NET Core
In This Topic
    Using Loupe with ASP.NET Core
    In This Topic

    Loupe provides an agent stack for .NET Standard and .NET 5 (and later) that includes support for ASP.NET Core.  Like .NET Core, Loupe is modular with different assemblies for extending common parts of the .NET Core ecosystem.

    While ASP.NET Core and EF Core support applications developed for the .NET Framework the Loupe agents are designed to work on top of the Loupe Agent for .NET Core exclusively at this time.  If you need them to work for .NET Framework, contact our support team for how to build them for this situation.
     Adding the Loupe Agent to your Application

    Add the the following NuGet packages to get Loupe and its relevant dependencies:

    1. Loupe.Agent.AspNetCore: The main Loupe extension for ASP.NET Core, which will also pull in the main Loupe agent itself.
    2. Loupe.Extensions.Logging: Connects Loupe with the Microsoft.Extensions.Logging infrastructure which is used by ASP.NET for common logging.
    3. Loupe.Agent.Core.Services: A small package with configuration builders for ASP.NET Core.
    4. Loupe.Agent.EntityFrameworkCore (Optional): Connects Loupe with EF Core to record performance and diagnostic information for EF Core.
    5. Loupe.Agent.PerformanceCounters (Optional): Records a collection of Windows Performance Counters on Windows systems.

    The recommended way to activate the ASP.NET Core Agent is to add it to the Loupe Agent Builder during the Host setup, typically in Program.cs like this:

    Host Builder Example for Program.cs
    Copy Code
        public static IHostBuilder CreateHostBuilder(string[] args) =>
                .AddLoupe(builder => builder.AddAspNetCoreDiagnostics()
                    .AddClientLogging() //The Loupe endpoint for client logging
                    .AddEntityFrameworkCoreDiagnostics() //EF Core monitoring
                    .AddPerformanceCounters()) //Windows Perf Counter monitoring

    The Loupe Agent for ASP.NET Core needs to access the HttpContext to monitor requests. This isn't always available by default in the ASP.NET Core Dependency Injection context, so we need to add it during the services collection in case it isn't pulled in by any other service. To do this, add the HttpContext Accessor at the top of the ConfigureServices call in the Startup class, like this:

    HttpContext Accessor for Startup.cs
    Copy Code
    public void ConfigureServices(IServiceCollection services)
        //The rest of your services

    Adding Client-side Logging

    The Loupe Agent for ASP.NET Core can create a logging endpoint so browser applications can add messages into the Loupe log.  In addition to adding the client side logging to your host builder (as done above) the endpoint has to be mapped and a cookie added to the request handling pipeline.

    To add the Loupe cookie-handling middleware in the app pipeline call UseLoupeCookies in your Configure method of the startup class used for the web site, typically in Startup.cs..  This should go before any Authentication or Routing call but after a Static Files call, if present.  For example:

    Loupe Cookie Handling
    Copy Code
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        // ...
        app.UseLoupeCookies(); // Add Loupe cookie-handling
        // ...

    To complete adding the endpoint to receive log messages from the client call MapLoupeClientLogger method in the Configure method as well.  For example:

    Typical Configuration Method
    Copy Code
     public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
             app.UseEndpoints(endpoints =>
                          name: "default",
                          pattern: "{controller}/{action=Index}/{id?}");


    .NET Core uses a different, more flexible, approach to application configuration than .NET Framework applications.  Instead of XML config files .NET Core has an entire extensible configuration subsystem that can be used.  In most situations you'll do a combination of coded configuration and JSON configuration.  For details, see Developer's Guide - Agent Configuration.

    Once you've instrumented an application you'll want to set up a connection with Loupe Server so you can collect data from everywhere your application runs and start managing errors.  Add this configuration to your appsettings.json file to send data to this server automatically in the background.  You'll need to make a few changes to this JSON to have it work:

    • Replace "Your Loupe Service Name" with the name of your Loupe Cloud-hosted Service.  If you don't have one yet, sign up for a free trial service.
    • Replace "Your Product" and "Your Application" with friendly values for your application.  A good analogy for Product is "Office" and Application is "Word", "Excel", and "PowerPoint". 
      "Logging": {
        "IncludeScopes": false,
        "LogLevel": {
          "Default": "Warning"
      "Loupe": {
        "Publisher": {
          "ProductName": "Your Product",
          "ApplicationName": "Your Application",
          "ApplicationType": "AspNet",
          "ApplicationVersionNumber": "1.0.1"
        "Server": {
          "UseGibraltarService": true,
          "CustomerName": "Your Loupe Service Name",
          "AutoSendSessions": true,
          "SendAllApplications": true

     Packaging and Sending Loupe Data from your Application
    The Loupe Agent provides a comprehensive set of capabilities to gather the session data recorded while your application runs and send it to where you can work with it to fix customer issues, understand feature usage, and drive your product development forward.  This capability is automatically configured as part of the Configuration Wizard, but you can provide an enhanced user experience by reviewing Developer's Guide - Packaging and Sending Data.

    Go Deeper with Loupe

    To get the most out of Loupe, refer to our Developer's Guide for .NET Core to see how you can create custom metrics, capture extended user information and more!

    See Also