LaunchDarkly multi-context sample (.NET)

LaunchDarkly Labs
This repository is maintained by LaunchDarkly Labs. While we try to keep it up to date, it is not officially supported by LaunchDarkly. For officially supported SDKs and tools, visit launchdarkly.com.

Description

A small ASP.NET Core sample that evaluates a boolean flag using a multi-context with user and request kinds, the LaunchDarkly server-side .NET SDK, and the LaunchDarkly Observability plugin (OpenTelemetry + flag evaluation hooks). It includes a web UI with a form, burst simulation for OTel-style traces, and indented JSON results (System.Text.Json with WriteIndented). Use it to learn multi-context evaluation and observability wiring; copy patterns into your own services via docs/IMPLEMENTING_MULTI_CONTEXT.md.

Requirements

• .NET 9 SDK (or retarget the project to net8.0 if you prefer)
• A LaunchDarkly server-side SDK key for your environment

Installation

1. Clone this repository.

2. Restore packages:

   dotnet restore LaunchDarklySample/LaunchDarklySample.csproj

3. Configure your SDK key (see Configuration: user secrets below)—do not commit secrets.

Quick start

cd LaunchDarklySample
dotnet user-secrets set "LaunchDarkly:SdkKey" "YOUR_SERVER_SIDE_SDK_KEY"
dotnet run

Open the URL shown in the console (often http://localhost:5268), set a flag key that exists in your project, and click Evaluate flag.

Usage

• Feature flag evaluation — Choose a boolean flag key, edit user and request (simulated) attributes, then evaluate. See Run for the full UI walkthrough.
• Burst simulation — Run multiple evaluations for the same user with delays to generate separate OpenTelemetry activities.
• Implementation guide — See docs/IMPLEMENTING_MULTI_CONTEXT.md to port multi-context patterns to other .NET apps.

Setting up a flag in LaunchDarkly

Do this once per environment you use with this sample.

1. Create context kinds (user and request)

1. In LaunchDarkly, open your project → Contexts (or Account settings → Contexts, depending on your UI).
2. Ensure you have context kinds named user and request.
   • If your project already has user, you only need to add request.
   • If you create new kinds, use the exact names user and request so they match the code (default user kind + ContextKind.Of("request")).

You will use these kinds when building targeting rules or experiments.

2. Create a boolean flag

1. Go to Feature flags → Create flag.
2. Choose Boolean (on/off).
3. Set the flag key to match this app’s config, e.g. sample-boolean-flag (or any key you prefer — then set LaunchDarkly:FlagKey to match).
4. Save the flag.

3. (Optional) Target by user or request

1. Open the flag → Targeting (or Rules).
2. Add rules that use context attributes for user (e.g. key, tier, country) and/or request (e.g. region, clientIp, sessionId).
3. The sample sends attributes such as:
   • User: user key, name, email, country, tier
   • Request: method, path, clientIp, userAgent, region, sessionId, edgePop, simulated

You can start with 100% on or off to validate wiring, then add rules.

4. Align the flag key in the app

The app reads LaunchDarkly:FlagKey (default sample-boolean-flag). If your flag key differs, set:

dotnet user-secrets set "LaunchDarkly:FlagKey" "your-flag-key"

Configuration: user secrets (full walkthrough)

This project reads settings under the LaunchDarkly section (see appsettings.json). Secrets (SDK key and anything you treat as sensitive) should live in the .NET User Secrets store so they are not committed to git.

The sample project already has a <UserSecretsId> in LaunchDarklySample.csproj, so you do not need dotnet user-secrets init unless you created a new project from scratch.

1. Open a terminal in the project folder

User secrets are tied to the project (the .csproj), not the solution file.

cd path/to/ld-dotnet-samplemulticontext/LaunchDarklySample

From the repo root you can also pass the project explicitly:

dotnet user-secrets --project LaunchDarklySample/LaunchDarklySample.csproj list

2. (Optional) Initialize user secrets

Only if your .csproj does not contain <UserSecretsId>...</UserSecretsId>:

dotnet user-secrets init

That adds a random UserSecretsId to the project file. This repo already includes one, so you can skip this step.

3. Set every LaunchDarkly value (copy and replace placeholders)

Run these from LaunchDarklySample/ (or add --project ... to each command). Replace the placeholder values with yours.

Required — server-side SDK key (from LaunchDarkly: Project settings → Environments → your environment → SDK key):

dotnet user-secrets set "LaunchDarkly:SdkKey" "sdk-xxxxxxxx-YourRealSdkKey"

Optional — flag key (must match the boolean flag’s key in LaunchDarkly; defaults to sample-boolean-flag in appsettings.json if unset):

dotnet user-secrets set "LaunchDarkly:FlagKey" "sample-boolean-flag"

Optional — observability service identity (shown in LaunchDarkly Observability for this app’s telemetry):

dotnet user-secrets set "LaunchDarkly:ServiceName" "ld-dotnet-sample-multicontext"
dotnet user-secrets set "LaunchDarkly:ServiceVersion" "1.0.0"

You can set only what you need. Minimum to run is LaunchDarkly:SdkKey.

4. Verify what is stored

dotnet user-secrets list

dotnet user-secrets list prints keys and values in plain text in your terminal (useful for debugging; avoid screen-sharing while it is visible). Example shape:

LaunchDarkly:SdkKey = sdk-abc123...
LaunchDarkly:FlagKey = sample-boolean-flag
LaunchDarkly:ServiceName = ld-dotnet-sample-multicontext
LaunchDarkly:ServiceVersion = 1.0.0

5. Remove or change a secret

dotnet user-secrets remove "LaunchDarkly:FlagKey"
dotnet user-secrets set "LaunchDarkly:FlagKey" "new-flag-key"

Clear all secrets for this project id:

dotnet user-secrets clear

Where secrets are stored on disk

User secrets are outside the repository. Typical locations:

OS	Path pattern
macOS / Linux	~/.microsoft/usersecrets/<UserSecretsId>/secrets.json
Windows	%APPDATA%\Microsoft\UserSecrets\<UserSecretsId>\secrets.json

The <UserSecretsId> is the GUID in LaunchDarklySample.csproj. Editing secrets.json by hand works, but dotnet user-secrets is safer.

Environment variables instead of user secrets

Anything under LaunchDarkly in configuration can be set with the double-underscore convention (useful in Docker, CI, or shell exports):

Configuration key	Environment variable
LaunchDarkly:SdkKey	LaunchDarkly__SdkKey
LaunchDarkly:FlagKey	LaunchDarkly__FlagKey
LaunchDarkly:ServiceName	LaunchDarkly__ServiceName
LaunchDarkly:ServiceVersion	LaunchDarkly__ServiceVersion

Example (one line in zsh/bash):

export LaunchDarkly__SdkKey="sdk-xxxxx"
export LaunchDarkly__FlagKey="sample-boolean-flag"
dotnet run --project LaunchDarklySample

Precedence (highest wins): environment variables → user secrets → appsettings.{Environment}.json → appsettings.json.

appsettings.json vs secrets

LaunchDarklySample/appsettings.json keeps non-secret defaults (e.g. FlagKey, ServiceName) and leaves SdkKey empty. Put real keys in user secrets or environment variables, not in committed JSON.

Run

dotnet run --project LaunchDarklySample

Open the root URL from LaunchDarklySample/Properties/launchSettings.json (often http://localhost:5268).

1. Set Flag key to the boolean flag you want to evaluate (defaults to LaunchDarkly:FlagKey from config, or sample-boolean-flag if unset). Leave blank to use that default.
2. Fill in User context (key, name, email, country, tier).
3. Adjust Simulated request context (fake client IP, User-Agent, region, session, edge POP, etc.) — these are not your real browser IP; they stand in for gateway-style data on the request context.
4. Optionally set Burst simulation: Number of simulated requests (1–100) and Delay between requests (ms) (0–60,000). The same user and same session are reused; each iteration gets a new request key (sim-{batchId}-{index}) and a child Activity (SimulatedRequest) under the HTTP request so OpenTelemetry / LaunchDarkly can show separate spans. Delays spread evaluations over time for metrics and charts.
5. Click Evaluate flag to see pretty-printed JSON including iterations, simulationBatchId, and timings.

When burst > 1, the optional Request key field is ignored (each iteration assigns its own key).

If the port is busy, run on another URL:

dotnet run --project LaunchDarklySample --urls "http://localhost:5288"

What this demonstrates

1. LdClient configured with ObservabilityPlugin (OTLP and ASP.NET Core instrumentation via the plugin’s dependencies).
2. TracingHook so flag evaluations attach compatible data to the active diagnostic activity (aligned with LaunchDarkly’s OpenTelemetry guidance for server-side .NET).
3. Context.MultiBuilder() combining a user context (with optional attributes) and a request context (with simulated request metadata) for BoolVariationDetail.
4. HTML UI with a dark theme and indented JSON output for quick inspection.
5. Burst simulation — repeated evaluations for one user with configurable delay, distinct request contexts, and per-iteration activities for OTel metrics/traces.

Documentation

• Implementing multi-context in another .NET app — concepts (context, kind, multi-context), step-by-step snippets for LdClient, Context.MultiBuilder, evaluation, optional observability hooks, and pitfalls.

Project layout

• LaunchDarklySample/Program.cs — web UI, SDK + observability setup, multi-context evaluation
• docs/IMPLEMENTING_MULTI_CONTEXT.md — portable implementation guide with code snippets
• LaunchDarklySample.sln — solution file
• CHANGELOG.md — version history (Keep a Changelog)

License

Apache License 2.0 — see the LICENSE file.

Changelog

See CHANGELOG.md.