Struct TenantScope
The tenant a single tenant-owned data request is bound to. A scope is either a Scoped(string?) value carrying a validated, non-empty tenant identifier, or Untenanted — the reserved partition for a row that belongs to no tenant. Both bind a concrete tenant term; there is no third state and no absent one.
public readonly struct TenantScope : IEquatable<TenantScope>
- Implements
- Inherited Members
- Extension Methods
Remarks
This type has no representation of "absent". TenantId is total: it is never null and never empty, for every inhabitant including default. A scope therefore always yields a tenant term to bind, so a statement that silently carries no tenant predicate cannot be produced from one.
That totality is the entire point, and it is why default is defined rather than merely discouraged. A value type always admits a default inhabitant, so an uninitialised scope is constructible whatever the API offers; making the default fold onto Untenanted means it is a legitimate, meaningful value rather than a hole that reads as "no tenant term" and disappears from an emitted statement. Absence cannot be reintroduced by omission.
Whether a deployment applies tenant confinement at all is a property of the deployment, not of a scope. A store that serves both single-tenant and multi-tenant hosts reads that from its own configuration and decides there whether to emit a predicate; it does not infer it from a missing tenant term. Keeping the two separate is what allows this type to stay total.
The empty-tenant guard lives here in one place (IsNullOrWhiteSpace(string)), so the fail-closed check has a single definition shared by every provider request and the tenant-scoping decorator, and yields exactly one exception type (TenantRequiredException).
Fields
UntenantedSentinel
The single reserved tenant identifier: the term bound for a genuinely untenanted row. A caller can
never construct it through Scoped(string?), so it can never collide with a real tenant.
It is a concrete, non-null value (never '', which Oracle folds to null).
public static readonly string UntenantedSentinel
Field Value
Remarks
Exposed so that schema and migration scripts can be generated from this constant instead of retyping the literal. Tenant-bound reads match this exact value, so a migration that backfills rows to a mistyped variant strands every one of them in a partition nothing queries — and does so silently: there is no compile-time signal, no constraint violation, and no runtime error, only rows that stop being returned. Reference this constant wherever the value has to appear in SQL or configuration.
The value is case-sensitive, like every tenant term here, and contains leading and trailing double underscores. Copy it from this field rather than from rendered documentation: markdown renderers treat the surrounding underscores as emphasis and can display a form that is not the value.
Deliberately static readonly rather than a const. A public
constant is inlined into every consuming assembly at compile time, so a consumer that referenced it
would keep the old literal until recompiled — leaving their rows in a partition this framework no
longer queries, with no error to signal it. A field is read at run time, so the value stays fixable
after ship and a consumer picks up the corrected one by upgrading the package alone.
Properties
TenantId
Gets the concrete tenant term to bind: a validated real tenant identifier for a Scoped(string?) scope, or UntenantedSentinel for Untenanted and for default. It is never null and never empty.
public string TenantId { get; }
Property Value
Remarks
A non-null value is not necessarily a real tenant: for the untenanted partition this returns the framework's reserved marker, which is observable here like any other value. Callers that surface a tenant identifier to a user, log it, or compare it against tenant data supplied from outside should account for that case rather than assuming every value names a real tenant. Scoped(string?) rejects the reserved marker, so it can never arrive here by that route.
Untenanted
Gets the reserved scope for a row that belongs to no tenant — a system-owned record, or a row written before multi-tenancy and anchored during a migration onto it. It binds the reserved UntenantedSentinel value, which Scoped(string?) rejects outright, so it can never be bound as a real tenant and never collide with one.
public static TenantScope Untenanted { get; }
Property Value
Remarks
This is the value default folds onto, so an uninitialised scope names the untenanted partition explicitly rather than carrying no term.
Methods
Equals(TenantScope)
Indicates whether the current object is equal to another object of the same type.
public bool Equals(TenantScope other)
Parameters
otherTenantScopeAn object to compare with this object.
Returns
Equals(object?)
Indicates whether this instance and a specified object are equal.
public override bool Equals(object? obj)
Parameters
objobjectThe object to compare with the current instance.
Returns
- bool
true if
objand this instance are the same type and represent the same value; otherwise, false.
FromContext(ITenantContext)
Derives the scope from an ambient tenant context, which is required: the context is converted through the single sentinel-aware conversion, which fails closed when the context resolves no tenant.
public static TenantScope FromContext(ITenantContext tenantContext)
Parameters
tenantContextITenantContextThe ambient tenant context. Required: this store partitions rows by tenant, and it resolves that partition from here, so there is no state in which the partition is undecided. A single-tenant host receives the framework default context and operates as the one canonical tenant.
Returns
- TenantScope
Untenanted when the context resolves the reserved sentinel; otherwise Scoped(string?) for the resolved tenant.
Remarks
There is deliberately no null-accepting form of this conversion. A conversion that accepted a missing context would have to invent a tenant term for it, silently turning "multi-tenancy was never registered here" into "this row belongs to no tenant". Those are not synonyms: the first is a question about the deployment, which a store answers from its own configuration, and conflating them has produced both an unscoped read and a delete that could only ever match nothing.
Exceptions
- ArgumentNullException
tenantContextis null.- TenantRequiredException
tenantContextresolves a null/whitespace tenant (multi-tenancy active but unresolved) — the store fails closed rather than binding a tenant the caller never established.- ArgumentException
tenantContextresolves a tenant longer than MaxLength characters. The ambient holder refuses such an id when the scope is established, so this is reachable only from a context that obtained its id elsewhere — a custom ITenantContext is the usual source.
GetHashCode()
Returns the hash code for this instance.
public override int GetHashCode()
Returns
- int
A 32-bit signed integer that is the hash code for this instance.
Scoped(string?)
Creates a scope bound to a real tenant. The tenant identifier is required: a null or whitespace value throws TenantRequiredException so a tenant-active request can never be constructed without a tenant (fail-closed by construction).
public static TenantScope Scoped(string? tenantId)
Parameters
tenantIdstringThe non-empty tenant identifier to scope the request to.
Returns
- TenantScope
A TenantScope bound to
tenantId.
Exceptions
- TenantRequiredException
tenantIdis null, empty, or whitespace.- ArgumentException
tenantIdis the reserved framework sentinel and therefore cannot name a real tenant, so an internal sentinel can never collide with a caller-supplied tenant; or is longer than MaxLength characters, which no shipped provider can store whole — rejected here rather than truncated later by a store, where a truncated identifier could collide with another tenant's.
Operators
operator ==(TenantScope, TenantScope)
Determines whether two scopes are equal.
public static bool operator ==(TenantScope left, TenantScope right)
Parameters
leftTenantScopeThe left scope.
rightTenantScopeThe right scope.
Returns
operator !=(TenantScope, TenantScope)
Determines whether two scopes are not equal.
public static bool operator !=(TenantScope left, TenantScope right)
Parameters
leftTenantScopeThe left scope.
rightTenantScopeThe right scope.