.NET Error Tracking installation

For ASP.NET Core projects, install the PostHog.AspNetCore package:

dotnet add package PostHog.AspNetCore

For other .NET projects, such as console applications, MAUI, or Blazor, install the core PostHog package:

dotnet add package PostHog

For ASP.NET Core, add PostHog to your Program.cs file:

using PostHog;

var builder = WebApplication.CreateBuilder(args);

builder.AddPostHog();

Configure your project token and host in appsettings.json:

{
  "PostHog": {
    "ProjectToken": "<ph_project_token>",
    "HostUrl": "https://us.i.posthog.com"
  }
}

For non-ASP.NET Core projects, initialize the core client as a singleton:

using PostHog;

public static readonly PostHogClient PostHog = new(new PostHogOptions {
    ProjectToken = "<ph_project_token>",
    HostUrl = new Uri("https://us.i.posthog.com"),
});

You can find your project token and instance address in the project settings page in PostHog.

The .NET SDK supports manual exception capture with CaptureException. It builds the $exception event for you, including exception type, message, stack frames, inner exceptions, aggregate exceptions, source context when available, and .NET runtime metadata.

The examples below assume posthog is an IPostHogClient from dependency injection, or your singleton PostHogClient.

try
{
    ProcessOrder(orderId);
}
catch (Exception exception)
{
    posthog.CaptureException(exception, "user_distinct_id");
}

Pass additional properties to add request, tenant, or domain context to the exception:

try
{
    ProcessOrder(orderId);
}
catch (Exception exception)
{
    posthog.CaptureException(
        exception,
        "user_distinct_id",
        new Dictionary<string, object>
        {
            ["order_id"] = orderId,
            ["environment"] = "production",
        }
    );
}

You can also attach feature flag values to the exception event with a feature flag snapshot:

var flags = await posthog.EvaluateFlagsAsync("user_distinct_id");

posthog.CaptureException(
    exception,
    "user_distinct_id",
    properties: null,
    groups: null,
    flags: flags
);

For ASP.NET Core, you can opt into automatic capture for unhandled request exceptions in the next step. Other .NET apps continue to use CaptureException manually.

ASP.NET Core automatic capture is available in PostHog.AspNetCore version 2.7.0 and later. Add the PostHog request context middleware after building the app, and enable exception capture:

var app = builder.Build();

app.UsePostHogRequestContext(options =>
{
    options.CaptureExceptions = true;
});

Place it before the request handlers whose unhandled exceptions you want to capture. If you use exception-handling middleware, register it first so it can handle the exception after PostHog throws it again. The PostHog middleware captures the exception with the active request context and adds the HTTP response status.

Trigger and capture a test exception to confirm events are being sent to PostHog. You should see it appear in the Error Tracking tab.

try
{
    throw new InvalidOperationException("Test exception from .NET");
}
catch (Exception exception)
{
    posthog.CaptureException(exception, "test_user");
    await posthog.FlushAsync();
}

For serverless environments, call FlushAsync() before the process exits so queued exception events are sent.