https://github.com/posthog/posthog-dotnet
A dotnet client sdk to the PostHog API
https://github.com/posthog/posthog-dotnet
Last synced: 3 months ago
JSON representation
A dotnet client sdk to the PostHog API
- Host: GitHub
- URL: https://github.com/posthog/posthog-dotnet
- Owner: PostHog
- License: mit
- Created: 2025-01-14T18:00:45.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-31T11:03:47.000Z (3 months ago)
- Last Synced: 2026-03-31T13:08:48.571Z (3 months ago)
- Language: C#
- Size: 1.39 MB
- Stars: 40
- Watchers: 7
- Forks: 14
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# PostHog DotNet Client SDK 
This repository contains a set of packages for interacting with the PostHog API in .NET applications.
This README is for those who wish to contribute to these packages.
For documentation on the specific packages, see the README files in the respective package directories.
## Packages
| Package | Version | Description
|---------|---------| -----------
| [PostHog.AspNetCore](src/PostHog.AspNetCore/README.md) | [](https://www.nuget.org/packages/PostHog.AspNetCore/) | For use in ASP.NET Core projects.
| [PostHog](src/PostHog/README.md) | [](https://www.nuget.org/packages/PostHog/) | The core library. Over time, this will support client environments such as Unit, Xamarin, etc.
| [PostHog.AI](src/PostHog.AI/README.md) | [](https://www.nuget.org/packages/PostHog.AI/) | AI Observability for OpenAI and other LLM providers.
> [!WARNING]
> These packages are currently in a pre-release stage. We're making them available publicly to solicit
> feedback. While we always strive to maintain a high level of quality, use these packages at your own
> risk. There *will* be many breaking changes until we reach a stable release.
## Platform
The core [PostHog](./src/PostHog/README.md) package targets `netstandard2.1` and `net8.0` for broad compatibility. The [PostHog.AspNetCore](src/PostHog.AspNetCore/README.md) package targets `net8.0`. The [PostHog.AI](src/PostHog.AI/README.md) package targets `netstandard2.1` and `net8.0` for broad compatibility.
## Building
To build the solution, run the following commands in the root of the repository:
```bash
$ dotnet restore
$ dotnet build
```
## Docs
More detailed docs for using this library can be found at [PostHog Docs for the .NET Client SDK](https://posthog.com/docs/libraries/dotnet).
## Samples
Sample projects are located in the `samples` directory.
To run the samples, you'll need to set your PostHog project API key. From the repository root you can run:
```bash
bin/user-secrets set PostHog:ProjectApiKey YOUR_API_KEY
```
The main ASP.NET Core sample app can be run with the following command:
```bash
$ bin/start
```
You can also run it from your favorite IDE or editor.
## Testing
To run the tests, run the following command in the root of the repository:
```bash
$ dotnet test
```
### Test Target Frameworks
The test projects target both `net8.0` and `netcoreapp3.1`. While .NET Core 3.1 reached end-of-life in December 2022, we continue to test against it because:
- It was the first runtime to fully support .NET Standard 2.1
- It serves as our minimum test baseline to ensure the `netstandard2.1` library works correctly on older runtimes
- It helps catch compatibility issues that might not surface on newer runtimes
This testing approach ensures broad compatibility without requiring users to install legacy runtimes in production.
## Publishing Releases
Releases are driven by PR labels. When a PR with the right labels is merged to `main`, a GitHub Actions workflow handles version bumping, tagging, creating a GitHub Release (with auto-generated notes), and publishing to NuGet.
### Release Process
1. Add the `release` label and exactly one of `bump-patch`, `bump-minor`, or `bump-major` to your PR
2. Merge the PR to `main`
3. Approve the release in the GitHub Environment gate (the workflow pauses for maintainer approval)
4. The workflow bumps the version in `Directory.Build.props`, commits to `main`, creates a git tag, and creates a GitHub Release
5. The GitHub Release triggers the [`main.yaml`](.github/workflows/main.yaml) workflow, which builds and publishes the packages to NuGet
## Installation
For ASP.NET Core projects, install the `PostHog.AspNetCore` package:
```bash
$ dotnet add package PostHog.AspNetCore
```
And register the PostHog services in `Program.cs` (or `Startup.cs`) file by calling the `AddPostHog` extension
method on `IHostApplicationBuilder` like so:
```csharp
using PostHog;
var builder = WebApplication.CreateBuilder(args);
builder.AddPostHog();
```
For other .NET projects, install the `PostHog` package:
```bash
$ dotnet add package PostHog
```
And if your project supports dependency injection, register the PostHog services in `Program.cs` (or `Startup.cs`)
file by calling the `AddPostHog` extension method on `IServiceCollection`. Here's an example for a console app:
```csharp
using PostHog;
var services = new ServiceCollection();
services.AddPostHog();
var serviceProvider = services.BuildServiceProvider();
var posthog = serviceProvider.GetRequiredService();
```
For a console app (or apps not using dependency injection), you can also use the `PostHogClient` directly, just make
sure it's a singleton:
```csharp
using System;
using PostHog;
var posthog = new PostHogClient(Environment.GetEnvironmentVariable("PostHog__PersonalApiKey"));
```
The `AddPostHog` methods accept an optional `Action` parameter that you can use to configure the
client. For examples, check out the [HogTied.Web sample project](../samples/HogTied.Web/Program.cs) and the unit tests.
## Usage
Inject the `IPostHogClient` interface into your controller or page:
```csharp
posthog.Capture(userId, "user signed up", new() { ["plan"] = "pro" });
```
```csharp
client.CapturePageView(userId, Request.Path.Value ?? "Unknown");
```
### Identity
#### Identify a user
See the [Identifying users](https://posthog.com/docs/product-analytics/identify) for more information about identifying users.
Identifying a user typically happens on the front-end. For example, when an authenticated user logs in, you can call `identify` to associate the user with their previously anonymous actions.
When `identify` is called the first-time for a distinct id, PostHog will create a new user profile. If the user already exists, PostHog will update the user profile with the new data. So the typical usage of `IdentifyAsync` here will be to update the person properties that PostHog knows about your user.
```csharp
await posthog.IdentifyAsync(
userId,
new()
{
["email"] = "haacked@posthog.com",
["name"] = "Phil Haack",
["plan"] = "pro"
});
```
#### Alias a user
Use the `Alias` method to associate one identity with another. This is useful when a user logs in and you want to associate their anonymous actions with their authenticated actions.
```csharp
await posthog.AliasAsync(sessionId, userId);
```
### Analytics
#### Capture an Event
Note that capturing events is designed to be fast and done in the background. You can configure how often batches are sent to the PostHog API using the `FlushAt` and `FlushInterval` settings.
```csharp
posthog.Capture(userId, "user signed up", new() { ["plan"] = "pro" });
```
#### Capture a Page View
```csharp
posthog.CapturePageView(userId, Request.Path.Value ?? "Unknown");
```
#### Capture a Screen View
```csharp
posthog.CaptureScreen(userId, "Main Screen");
```
### Feature Flags
#### Check if feature flag is enabled
Check if the `awesome-new-feature` feature flag is enabled for the user with the id `userId`.
```csharp
var enabled = await posthog.IsFeatureEnabledAsync(userId, "awesome-new-feature");
```
You can override properties of the user stored on PostHog servers for the purposes of feature flag evaluation.
For example, suppose you offer a temporary pro-plan for the duration of the user's session. You might do this:
```csharp
if (await posthog.IsFeatureEnabledAsync(
"pro-feature",
"some-user-id",
personProperties: new() { ["plan"] = "pro" }))
{
// Access to pro feature
}
```
If you have group analytics enabled, you can also override group properties.
```csharp
if (await posthog.IsFeatureEnabledAsync(
"large-project-feature",
"some-user-id",
new FeatureFlagOptions
{
Groups = [new Group(groupType: "project", groupKey: "project-group-key") { ["size"] = "large" }]
}))
{
// Access large project feature
}
```
> [!NOTE]
> Specifying `PersonProperties` and `GroupProperties` is necessary when using local evaluation of feature flags.
### Get a single Feature Flag
Some feature flags may have associated payloads.
```csharp
if (await posthog.GetFeatureFlagAsync("awesome-new-feature", "some-user-id") is { Payload: {} payload })
{
// Do something with the payload.
Console.WriteLine($"The payload is: {payload}");
}
```
### Get All Feature Flags
Using information on the PostHog server.
```csharp
var flags = await posthog.GetAllFeatureFlagsAsync("some-user-id");
```
Overriding the group properties for the current user.
```csharp
var flags = await posthog.GetAllFeatureFlagsAsync(
"some-user-id",
options: new AllFeatureFlagsOptions
{
Groups =
[
new Group("project", "aaaa-bbbb-cccc")
{
["$group_key"] = "aaaa-bbbb-cccc",
["size"] = "large"
}
]
});
```