Skip to main content

Reliability and Error Handling (.NET)

Server-side .NET apps can fail when fetching, verifying, or loading cached feature definitions (network blips, JWKS rotation, storage round-trips). The SDK keeps evaluation predictable while making those failures visible.

Shared behavior​

  • OnError reports fetch, cache, storage, signature, and JWKS failures.
  • After a successful load, refresh failures keep in-memory last-known-good flags.
  • Signed snapshots store the exact server defs JSON (SignedDefsJson) so cold start verification does not re-serialize models (which caused false Invalid signature errors). Evaluation always uses that verified JSON.
  • If a typed Features copy is also present and does not match the verified SignedDefsJson (feature keys, filters/parameters, secured flag, requirement type, metrics), the snapshot is refused (possible storage tampering) and reported via OnError.
  • Legacy snapshots without SignedDefsJson are refused when UseSignedDefinitions is enabled. Clear persisted snapshots and refresh to upgrade them (typed Features alone are not trusted).
  • WebSocket signing-key-updated clears the JWKS cache/snapshot, then refreshes definitions (clear completes before refresh).
  • Definitions revision is taken from typed ETag, raw ETag, or X-Definitions-Revision. Revision is for conditional HTTP caching — it is not part of the cryptographic signature.
  • Definitions and JWKS HTTP error status messages do not include remote response bodies at Information/Error level. Enable Debug logging for Toggly.FeatureManagement to inspect response bodies when troubleshooting.

OnError​

services.Configure<TogglySettings>(options =>
{
    options.AppKey = Configuration["Toggly:AppKey"];
    options.Environment = Configuration["Toggly:Environment"];
    options.UseSignedDefinitions = true;
    options.OnError = (message, exception) =>
    {
        // Report to App Insights / Sentry / your logger
        logger.LogWarning(exception, "Toggly: {Message}", message);
    };
});

The last error is also available via IFeatureProviderDebug.GetDebugInfo() (the concrete TogglyFeatureProvider is registered as that interface).

Clearing snapshots​

Use clear APIs when recovering from a corrupt cache, after key rotation issues, or in tests:

// Clears persisted feature + JWKS snapshots (does not wipe in-memory defs)
var provider = app.Services.GetRequiredService<TogglyFeatureProvider>();
await provider.ClearPersistedSnapshotsAsync();

// Or call the snapshot provider directly
var snapshots = app.Services.GetRequiredService<IFeatureSnapshotProvider>();
await snapshots.ClearSnapshotAsync();
await snapshots.ClearJwkSnapshotAsync();

After clearing, the next refresh rebuilds the snapshot from the definitions API. In-memory definitions stay until that refresh succeeds.