.NET

⚠️ Warning: This is in beta and may break.

This is an optional library you can install if you're working with .NET Core. It uses an internal queue to make calls fast and non-blocking. It also batches requests and flushes asynchronously, making it perfect to use in any part of your web app or other server side application that needs performance.

Installation

At the moment, ASP.NET Core is the only supported platform for the PostHog .NET SDK.

dotnet add package PostHog.AspNetCore

In your Program.cs file, add the following code:

using PostHog.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.AddPostHog();

Make sure to configure PostHog with your project API key, instance address, and optional personal API key. For example, in appsettings.json:

{
  "PostHog": {
    "ProjectApiKey": "phc_...",
    "Host": "https://us.i.posthog.com"
  }
}

Note: If the host is not specified, the default host https://us.i.posthog.com is used.

Use a secrets manager to store your personal API key. For example, when developing locally you can use the UserSecrets feature of the dotnet CLI:

dotnet user-secrets init
dotnet user-secrets set "PostHog:PersonalApiKey" "phc_..."

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

To see detailed logging, set the log level to Debug or Trace in appsettings.json:

{
  "DetailedErrors": true,
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "PostHog": "Trace"
    }
  },
  ...
}

Capturing events

You can send custom events using capture:

posthog.Capture("distinct_id_of_the_user", "user_signed_up");

Tip: We recommend using a [object] [verb] format for your event names, where [object] is the entity that the behavior relates to, and [verb] is the behavior itself. For example, project created, user signed up, or invite sent.

Setting event properties

Optionally, you can also include additional information in the event by setting the properties value:

posthog.Capture(
    "distinct_id_of_the_user", 
    "user_signed_up", 
    properties: new() {
        ["login_type"] = "email", 
        ["is_free_trial"] = "true"
    }
);

Sending page views

If you're aiming for a backend-only implementation of PostHog and won't be capturing events from your frontend, you can send $pageview events from your backend like so:

using PostHog;
using Microsoft.AspNetCore.Http.Extensions;

posthog.CapturePageView(
    "distinct_id_of_the_user",
    context.HttpContext.Request.GetDisplayUrl());

Person profiles and properties

The .NET SDK captures identified events by default. These create person profiles. To set person properties in these profiles, include them when capturing an event:

posthog.Capture(
    "distinct_id",
    "event_name",
    personPropertiesToSet: new() { ["name"] = "Max Hedgehog" },
    personPropertiesToSetOnce: new() { ["initial_url"] = "/blog" }
);

For more details on the difference between $set and $set_once, see our person properties docs.

To capture anonymous events without person profiles, set the event's $process_person_profile property to false:

posthog.Capture(
    "distinct_id",
    "event_name",
    properties: new() {
        ["$process_person_profile"] = false
    }
)

Alias

Sometimes, you want to assign multiple distinct IDs to a single user. This is helpful when your primary distinct ID is inaccessible. For example, if a distinct ID used on the frontend is not available in your backend.

In this case, you can use alias to assign another distinct ID to the same user.

await posthog.AliasAsync('current_distinct_id', 'new_distinct_id');

We strongly recommend reading our docs on alias to best understand how to correctly use this method.

Group analytics

Group analytics allows you to associate an event with a group (e.g. teams, organizations, etc.). Read the group analytics guide for more information.

Note: This is a paid feature and is not available on the open-source or free cloud plan. Learn more on our pricing page.

To capture an event and associate it with a group, add the groups argument to your Capture call:

postHogClient.Capture(
    "user_distinct_id", 
    "some_event", 
    groups: [new Group("company", "company_id_in_your_db")]);

Update properties on a group, use the GroupIdentifyAsync method:

await postHogClient.GroupIdentifyAsync(
    type: "company",
    key: "company_id_in_your_db",
    name: "Awesome Inc.",
    properties: new()
    {
        ["employees"] = 11
    }
);

The name is a special property which is used in the PostHog UI for the name of the group. If you don't specify a name property, the group ID will be used instead.

Feature flags

PostHog's feature flags enable you to safely deploy and roll back new features.

There are 2 steps to implement feature flags in .NET:

Step 1: Evaluate the feature flag value

Boolean feature flags

var isMyFlagEnabled = await posthog.IsFeatureEnabledAsync(
    "flag-key",
    "distinct_id_of_your_user"
);
if (isMyFlagEnabled.GetValueOrDefault())
{
    // Feature is enabled
}
else
{
    // Feature is disabled    
}

Note: The IsFeatureEnabledAsync method returns a nullable boolean. If the flag is not found or evaluating it is inconclusive, it returns null.

Multivariate feature flags

var flag = await posthog.GetFeatureFlagAsync(
    "flag-key",
    "distinct_id_of_your_user"
);

// replace "variant-key" with the key of your variant
if (flag is { VariantKey: "variant-key"} ) {
    // Do something differently for this user
    // Optional: fetch the payload
    var matchedPayload = flag.Payload;
}

The GetFeatureFlagAsync method returns a nullable FeatureFlag object. If the flag is not found or evaluating it is inconclusive, it returns null. However, there is an implicit conversion to bool to make comparisons easier.

if (await posthog.GetFeatureFlagAsync(
    "flag-key",
    "distinct_id_of_your_user")
)
{
    // Do something differently for this user
}

Step 2: Include feature flag information when capturing events

If you want use your feature flag to breakdown or filter events in your insights, you'll need to include feature flag information in those events. This ensures that the feature flag value is attributed correctly to the event.

Note: This step is only required for events captured using our server-side SDKs or API.

There are two methods you can use to include feature flag information in your events:

Method 1: Include the $feature/feature_flag_name property

In the event properties, include $feature/feature_flag_name: variant_key:

posthog.Capture(
    "distinct_id_of_your_user",
    "event_name",
    properties: new() {
        // replace feature-flag-key with your flag key.
        // Replace 'variant-key' with the key of your variant
        ["$feature/feature-flag-key"] = "variant-key"
    }
);

Method 2: Set send_feature_flags to true

The Capture() method has an optional argument sendFeatureFlags, which is set to false by default. By setting this to true, feature flag information will automatically be sent with the event.

Note that by doing this, PostHog will make an additional request to fetch feature flag information before capturing the event. So this method is only recommended if you don't mind the extra API call and delay.

posthog.Capture(
    "distinct_id_of_your_user",
    "event_name",
    properties: null,
    groups: null,
    sendFeatureFlags: true
);

Fetching all flags for a user

You can fetch all flag values for a single user by calling GetAllFeatureFlagsAsync().

This is useful when you need to fetch multiple flag values and don't want to make multiple requests.

var flags = await posthog.GetAllFeatureFlagsAsync(
    "distinct_id_of_your_user"
);

Sending $feature_flag_called events

Capturing $feature_flag_called events enable PostHog to know when a flag was accessed by a user and thus provide analytics and insights on the flag. By default, we send a these event when:

1. You call posthog.GetFeatureFlagAsync() or posthog.IsFeatureEnabledAsync(), AND
2. It's a new user, or the value of the flag has changed.

Note: Tracking whether it's a new user or if a flag value has changed happens in a local cache. This means that if you reinitialize the PostHog client, the cache resets as well – causing $feature_flag_called events to be sent again when calling GetFeatureFlagAsync or IsFeatureEnabledAsync. PostHog is built to handle this, and so duplicate $feature_flag_called events won't affect your analytics.

You can disable automatically the additional request to capture $feature_flag_called events. For example, when you don't need the analytics, or it's being called at such a high volume that sending events slows things down.

To disable it, set the sendFeatureFlagsEvent option in your function call, like so:

var isMyFlagEnabled = await posthog.IsFeatureEnabledAsync(
    "flag-key", 
    "distinct_id_of_your_user",
    options: new FeatureFlagOptions
    {
        SendFeatureFlagEvents = true
    }
);
// will not send `$feature_flag_called` events

Advanced: Overriding server properties

Sometimes, you may want to evaluate feature flags using person properties, groups, or group properties that haven't been ingested yet, or were set incorrectly earlier.

You can provide properties to evaluate the flag with by using the person properties, groups, and group properties arguments. PostHog will then use these values to evaluate the flag, instead of any properties currently stored on your PostHog server.

For example:

var flag = await posthog.GetFeatureFlagAsync(
    "flag-key",
    "distinct_id_of_the_user",
    options: new FeatureFlagOptions
    {
        PersonProperties = new() { ["property_name"] = "value" },
        Groups = [
            new Group("your_group_type", "your_group_id")
            {
                ["group_property_name"] = "your group value"
            },
            new Group(
                "another_group_type",
                "another_group_id",
                new Dictionary<string, object?>
                {
                    ["group_property_name"] = "another group value"
                }
            )
        ]
    });

Overriding GeoIP properties

By default, a user's GeoIP properties are set using the IP address they use to capture events on the frontend. You may want to override the these properties when evaluating feature flags. A common reason to do this is when you're not using PostHog on your frontend, so the user has no GeoIP properties.

Currently PostHog does not provide a way to override GeoIP properties using our SDKs. Our API, however, does allow you do this. See our API docs on how to override GeoIP properties for more details.

Local evaluation

Evaluating feature flags requires making a request to PostHog for each flag. However, you can improve performance by evaluating flags locally. Instead of making a request for each flag, PostHog will periodically request and store feature flag definitions locally, enabling you to evaluate flags without making additional requests.

It is best practice to use local evaluation flags when possible, since this enables you to resolve flags faster and with fewer API calls.

For details on how to implement local evaluation, see our local evaluation guide.

Experiments (A/B tests)

Since experiments use feature flags, the code for running an experiment is very similar to the feature flags code:

if (await posthog.GetFeatureFlagAsync(
        "experiment-feature-flag-key",
        "user_distinct_id")
    is { VariantKey: "variant-name" })
{
    // Do something
}

It's also possible to run experiments without using feature flags.

GeoIP properties

The posthog-dotnet library disregards the server IP, does not add the GeoIP properties, and does not use the values for feature flag evaluations.

Serverless environments (Azure Functions/Render/Lambda/...)

By default, the library buffers events before sending them to the /batch endpoint, for better performance. This can lead to lost events in serverless environments, if the .NET process is terminated by the platform before the buffer is fully flushed. To avoid this, you can:

• ensure that await posthog.FlushAsync() is called after processing every request, by adding a middleware to your server: this allows posthog.Capture() to remain asynchronous for better performance.