Skip to content

Audiences

An audience is a named group a tenant, a user or the system caller can belong to. The model declares which audiences exist. Who holds them is runtime data and changes without a redeploy.

IAudienceSource is the one abstraction you implement over your storage:

Member Purpose
GetGrants(subject, cancellationToken) The AudienceGrants that apply to an AudienceSubject (tenant, user, system), each tagged with its AudienceLevel.
OnChanged(handler) Subscribes to AudienceChange notifications, so a host can invalidate what it cached. Dispose the result to unsubscribe.

An AudienceSubject can also carry the calling system’s client id in SystemClientId, set with an object initializer (new AudienceSubject(tenant, user, IsSystem: true) { SystemClientId = "billing" }). It is empty when the caller names none. The resolver hands the subject to the source unchanged, so a source can return the system-wide grants plus that system’s own; a caller with no client id gets the system-wide grants only.

InMemoryAudienceSource is a complete implementation for specifications and samples. Its Grant and Withdraw methods take effect immediately and notify subscribers. Withdrawing at one level leaves the other levels alone.

IAudienceResolver.Resolve(subject) returns EffectiveAudiences: the union of the tenant, user and system grants. There is no precedence between levels.

Member Meaning
Matching The declared audiences held. Only these match a gate.
Undeclared Grants whose audience the model does not declare.
Holds(audience) Whether a declared audience is held.

A grant for an undeclared audience is carried and reported, never dropped and never matched. Register an IUndeclaredAudienceObserver to be told about them, for example to show them to an operator. Declaring the audience later makes the old grant live again.

For local development and test runs you can grant every declared audience to every request, so you see the whole application:

services.AddAvailability(options =>
{
options.EnvironmentName = environment.EnvironmentName;
options.GrantAllDeclaredAudiences = true;
});

The switch is off by default. It is allowed only in the Development, Local, Test and Testing environments. In any other environment, including Production, an environment with no name, or a name that is not recognized, setting it throws EnvironmentSwitchRefusedException: from AddAvailability and AudienceResolver at startup, and from Resolve if it is turned on afterwards. Grants for undeclared audiences still do not match while the switch is on.