Skip to main content

.NET SDK

Use Toggly's .NET SDK in .NET and .NET Core applications. For an offline dashboard hosted inside your ASP.NET Core app, see Embedded dashboard.

Quick reference

Grab the printable .NET cheat sheet (download PDF) — DI, FeatureGate, snapshot providers, Hangfire, NSwag, health checks.

Installation​

Install the Toggly.FeatureManagement.Web package

Install-Package Toggly.FeatureManagement.Web

Initialization​

Register the SDK once in Program.cs. The SDK downloads and caches definitions; flag checks use those definitions in your process.

using Toggly.FeatureManagement.Configuration;
using Toggly.FeatureManagement.Web;
using Toggly.FeatureManagement.Web.Configuration;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllersWithViews();
builder.Services.AddTogglyWeb(options =>
{
    // Supply configuration through environment variables or your normal secret provider.
    options.AppKey = builder.Configuration["Toggly:AppKey"]
        ?? throw new InvalidOperationException("Set Toggly:AppKey before startup.");
    options.Environment = builder.Configuration["Toggly:Environment"] ?? "Production";
    options.UndefinedEnabledOnDevelopment = false; // Unknown flags stay off.
})
.WithTogglyTargeting<HttpContextTargetingContextAccessor>();

var app = builder.Build();
app.MapDefaultControllerRoute();
app.Run();

For example, Toggly__AppKey and Toggly__Environment configure these settings through ASP.NET Core's environment provider. Create the app and flag in Toggly before running this example; keep the key out of source control.

Supply identity before the first check​

AddTogglyWeb registers HTTP filters and access to the current request. The explicit WithTogglyTargeting call adds the targeting accessor: it reads HttpContext.User.Identity.Name as the stable user ID and claims of type group as memberships. UserClaims filters read the current principal's claims. Configure your normal authentication middleware before controller execution so the principal is available before any feature check. Do not use a client-supplied user ID header as authentication.

The accessor caches targeting context in HttpContext.Items for that request. It does not change a process-wide user. A new request can evaluate a different identity using the same cached definitions, without fetching definitions again. Use WithTogglyTargeting for Toggly's targeting semantics rather than registering Microsoft's separate targeting filter with WithTargeting.

Try your first flag​

  1. In your Toggly app's environment, create new-dashboard and leave it off.
  2. Evaluate that exact key with IsEnabledAsync("new-dashboard"), or use a Razor <feature name="new-dashboard"> gate.
  3. Enable the flag with an Always On rule, allow the SDK to receive the definition update, then reload the page. The gated content appears without redeploying the application.
  4. Add user targeting and test two authenticated users. A feature flag changes availability; your existing authorization rules must still protect the operation.

Quick Start​

Using FeatureGate Attribute​

Entire controllers, or individual actions can be annotated with the FeatureGate attribute. If the feature is off, they can't execute

[FeatureGate(FeatureFlags.Users)]
[Route("users")]
[Controller]
public class UsersController : Controller
{
    ...
}

Using IFeatureManagerSnapshot​

The IFeatureManagerSnapshot service can be injected anywhere else more suitable helper methods aren't available.

private readonly IFeatureManagerSnapshot _featureManager;

public UsersController(IFeatureManagerSnapshot featureManager)
{
    _featureManager = featureManager;
}

[Route("")]
public async Task<IActionResult> Index()
{
    var feature1Enabled = await _featureManager.IsEnabledAsync(FeatureFlags.Feature1);

    return View(feature1Enabled ? "Feature1Index" : "Index");
}
info

IFeatureManagerSnapshot keeps the first Boolean result for each feature during a request. Use it when the user and evaluation context stay the same. When checking the same flag for several distinct entities, use IFeatureManager with each entity instead; a cached result for one Order must not decide another Order. See Entity context.

Performance​

The Toggly .NET SDK is optimized for high performance with minimal overhead:

  • Feature flag evaluation: ~360 nanoseconds (0.36 microseconds)
  • Memory per evaluation: ~1.55 KB
  • Throughput: Over 2.7 million evaluations per second per core
  • Targeting overhead: 2-5x for complex rules

👉 View detailed performance benchmarks →

Next Steps​

Working example​

Explore the .NET SDK Sample. Its guided sections include the first flag, request identity, Order VIP targeting, filter presets, named variants, Hangfire, health checks, and OpenAPI filtering. The README maps each section to its source files and includes a manual walkthrough.