.NET client reference
This page is the reference for developers using the .NET SDK: every option and member. It lists the configuration options and consumer surface of the .NET client SDK (targets netstandard2.1).
The SDK is two public NuGet packages, and dotnet add package Sidub.Licensing.Client brings in
both: Sidub.Licensing.Client defines the registration entry point (AddSidubLicensing()),
while the types you program against (LicensingServiceOptions, ILicensingService,
LicensingContextAccessor, LicensingServiceReference) live in the core Sidub.Licensing
package it depends on, under the Sidub.Licensing and Sidub.Licensing.Services namespaces.
LicensingServiceOptions fields
Section titled “LicensingServiceOptions fields”| Field | Meaning |
|---|---|
LicenseServiceUri |
The licensing API URL to call. Required. |
ConsumptionServiceUri |
The consumption API URL to call. Optional; set it when you report usage. |
EncodedCredential |
The encoded credential (SIDUB_LIC_...) carrying the seat id, the service key and the seat’s runtime token. The recommended way to configure credentials. |
ServiceKeyVersion |
Server-side key registration only; not part of the encoded credential. |
BillableResourceId |
Optional resource id to attribute metered consumption to. |
IssuerClientId |
Your account’s client id. Set it: every runtime call declares the seller, and a credential another seller issued is refused, so a credential bought for someone else’s product cannot unlock yours because the feature keys match. Also applied to embedded checkout requests that do not specify one. |
ProductId |
This product’s id. With it a credential of another product is refused, your own other products included. |
AuthorizationTimeoutSeconds |
Per-attempt time budget for the authorization fetch. Default 10; values below 1 are clamped to 1. |
AuthorizationStaleGraceMinutes |
How long the last verified authorization may be served past expiry when a refresh fails because the service is unreachable. Default 60; 0 disables grace. A denial or signature failure is never served stale. |
ILicensingService members
Section titled “ILicensingService members”| Member | Purpose |
|---|---|
GetAuthorization |
Retrieves the current authorization for the configured seat. |
GetLicenseFeature<T> |
Retrieves a specific license feature by type. Returns null when the feature is absent from the license; check before using the result. |
PerformOperation<TFeature,TState> |
Performs an operation against a feature, carrying state through the call. |
AssertLicense |
Confirms the license satisfies a given assertion, and returns whether it holds. A rate-limit assertion that does not hold throws RateLimitException, and an allowance assertion throws AllowanceExhaustedException. A limit assertion returns false. |
GetLicenseFeatureState<TFeature,TState> |
Retrieves the current state of a license feature: for a rate-limited feature, its consumption; for an allowance, what this process knows of the period. It asks the platform nothing. |
SetLicenseFeatureState<TFeature,TState> |
Sets the state of a license feature. |
Every member takes two leading arguments: a LicensingServiceReference identifying the
configured service, and the resolved LicensingContext carrying the credential:
GetAuthorization(serviceReference, context). LicensingContextAccessor resolves the context
for you, and the AI-assisted path’s implement_base output shows the wiring end to end; see
AI-assisted setup.
Supporting types
Section titled “Supporting types”| Type | Meaning |
|---|---|
LicensingContextAccessor |
Provides access to the current licensing context. |
LicensingServiceReference |
A reference to the configured licensing service. |
LicensingConsumptionBuffer |
Aggregates recorded uses and reports them on a timer; FlushAsync reports everything buffered now. See Consumption buffer. |
LicensingCredential |
The decoded SIDUB_LIC_... value: SeatId, ServiceKeyId, ServiceKeyPublicMember and RuntimeToken. CurrentVersion is 2; ToEncodedString() writes it back. A version 1 payload named the seat LicenseId and is refused, not reinterpreted. |
QuotaLicenseFeature |
An allowance on the license: FeatureKey and Allowance, the uses per billing period. Zero or less is no cap: every use is counted and reported, none is refused, and no grant is taken. |
QuotaLicenseAssertion |
Covers(featureKey) asserts, before the work, that the use it will record fits the allowance; pass amount when the work records several uses. It records nothing. Create(featureKey) asserts the last use was within the allowance, and asks the platform nothing. Through AssertLicense either returns true or throws AllowanceExhaustedException, and returns false for a feature the license does not carry. |
AssertAllowance |
licensing.AssertAllowance(serviceReference, context, featureKey) checks before the work that the use it will record fits the allowance: the same as AssertLicense with QuotaLicenseAssertion.Covers(featureKey). The optional amount, default 1, is how many uses the work will record. Returns true, throws AllowanceExhaustedException, or returns false when the license does not carry the allowance. Records nothing. An extension on ILicensingService. |
QuotaLicenseFeatureState |
The state of an allowance as this process knows it. It is read-only to the application. Read it through Allowance, Remaining, Reserved, PeriodEndUtc, AsOfUtc, GetConsumption() and IsWithinAllowance(). GetConsumption() is the uses recorded in the period, with those this process has recorded since. After the platform refuses a use because the period is spent, Remaining is 0 and PeriodEndUtc is when the period resets. |
ReadAllowanceState |
licensing.ReadAllowanceState(serviceReference, context, feature) returns the QuotaLicenseFeatureState for display, reading the figures from the platform first when none are held or those held are more than a minute old. It takes no units and does not throw for a read that fails: the figures held stand, the failure is logged (ALLOWANCE-READ-FAILED), and the platform is not asked again for 30 seconds. An extension on ILicensingService; ILicenseStateProvider.GetState calls it. |
LimitLicenseFeature |
A limit on the license: FeatureKey and Limit, a number the application holds to, such as 10 projects. null is unlimited. The platform never counts it: the application counts its own data. Read by SDK 2.4.0 or later; an older .NET SDK (before 2.4.0) fails the whole authorization for a license carrying a Limit, not just that feature. |
LimitLicenseAssertion |
Create(featureKey, count) asserts that count, the number the application would hold after the action, is within the limit: with a limit of 3, creating the fourth project asserts 4 and does not hold. Through AssertLicense it returns true or false, and false for a feature the license does not carry as a limit. It never throws for a count past the limit, and records nothing. |
GetLimit |
licensing.GetLimit(serviceReference, context, featureKey) reads the limit without asserting, to show “7 of 10” or size a control: a LimitReading(FeatureKey, Limit) with IsUnlimited, or null when the license does not carry the feature as a limit. An extension on ILicensingService. |
LicensingConsumptionBufferOptions |
Bounds on the consumption buffer: FlushIntervalMs (15000), MaxBufferedEvents (100), MaxRetryAttempts (3), RetryBaseDelayMs (500), MaxRetryBackoffMs (300000), SubmitTimeoutMs (10000), MaxConcurrentSubmissions (4), MaxPendingAggregates (10000) and DisposeFlushTimeoutMs (5000). Validated at startup. In the Sidub.Licensing.Client namespace. |
ILicenseStateProvider |
GetState(serviceReference, context) returns a LicenseStateView of the seat. Its Allowances are AllowanceView(FeatureKey, Allowance, Used, Remaining, PeriodEndUtc) with Reserved and AsOfUtc. Reading the state reads the figures from the platform when none are held for the period or those held are more than a minute old; the read uses none of the allowance. The figures are unknown while PeriodEndUtc is null. Its Limits are a LimitReading for each limit feature, with no usage: the application keeps its own count. In the Sidub.Licensing.Client namespace. |
Enforcing an allowance covers how a use is recorded, checked and refused, what the figures read, and what happens when the application stops: the SDK settles with the platform by itself, and there is nothing to wire or call.
Credentials
Section titled “Credentials”LicensingCredential and LicensingContext carry one secret: RuntimeToken, a seat-scoped
token that authorizes and meters the one seat it names. LicensingContext requires it, and
there is no account key on either type; the account API key is a server-side seller identity and
never travels inside a credential.
The SDK calls {LicenseServiceUri}/runtime and {ConsumptionServiceUri}/runtime and presents the
token as Authorization: Bearer. The /runtime suffixes are derived by the SDK, so set
LicenseServiceUri and ConsumptionServiceUri to the plain addresses. The service-path constants
are on LicensingServiceReference as LicensingApiRuntimeServicePath (.Api.Runtime) and
LicensingConsumptionRuntimeServicePath (.Consumption.Runtime).
LicensingContextAccessor refuses a context with no RuntimeToken, with
LicensingConfigurationException. ILicenseAuthorizationProvider.GetAuthorization takes the token
directly:
GetAuthorization(LicensingServiceReference serviceReference, Guid seatId, string? runtimeToken = null).
A null token is legitimate: a server-mode composition authorizes locally and reaches no
gateway.
Errors
Section titled “Errors”API failures throw LicensingApiException (namespace Sidub.Licensing.Exceptions), carrying
the same error contract every HTTP surface returns:
| Member | Meaning |
|---|---|
Code |
Machine-readable error code (PascalCase, e.g. ValidationError, AuthorizationDenied, NotFound, ServerError). Branch on this, not on message text. |
Message |
The server’s human-readable description (falls back to a client description when no body was received). |
CorrelationId |
The id the server logged the failure under; quote it when contacting support. |
StatusCode |
The HTTP status of the failed response, when one was received. |
Details |
Structured per-field entries (Code, Message, Field, TargetId); empty when none were sent. |
RetryAfter |
The server’s Retry-After backpressure hint, when sent. Don’t retry sooner. |
The authorization fetch retries transient failures (timeouts, 429, 5xx) with bounded backoff,
honouring Retry-After; exhaustion surfaces LicenseAuthorizationUnavailableException with the
last LicensingApiException as its inner exception. A definitive refusal is not retried.
An enforcement denial is typed. A 403 AuthorizationDenied that names its reason throws
LicenseAuthorizationDeniedException (namespace Sidub.Licensing), carrying SeatId and a
Reason of Expired, LicenseSuspended, LicenseCancelled, SeatRetired or ProductMismatch (the
credential is for another seller or product than IssuerClientId/ProductId declare), so you can tell
a retired seat from a suspended license without reading the message. An authorization that has
expired locally throws the same exception. Any other refusal (an unknown seat, a revoked
credential, a denial with no reason) throws LicensingApiException with its Code.
Rate-limit enforcement of your own features still throws RateLimitException locally.
A signed answer (an authorization, an allowance grant or a reading) that fails verification, or
that names a signature layout this SDK does not read, throws LicenseVerificationException
(namespace Sidub.Licensing.Exceptions) and logs the update it needs. Every runtime call states
the newest layout the SDK reads (SignatureLayout.Current), so a later change to what is signed
is a new layout served beside the old one, not a break. A 429 LedgerBusy or 503 StoreUnavailable
from the runtime paths is retried by the SDK under the same RequestId, honouring Retry-After.
PerformOperation on an allowance throws LicenseAuthorizationUnavailableException when it
needs the platform and cannot reach it, and throws it for the next 30 seconds without trying
again. A use the allowance does not cover throws AllowanceExhaustedException (namespace
Sidub.Licensing.Exceptions) and is neither counted nor reported. It carries FeatureKey,
Allowance and PeriodEndUtc, when the period resets. Its Message says either that the period
has no units left or that it does not cover so many more uses.
Consumption buffer
Section titled “Consumption buffer”AddSidubLicensing() registers LicensingConsumptionBuffer (namespace Sidub.Licensing.Client)
as a singleton. It aggregates the uses your application records and reports them on a timer, so a
use is not sent the moment it happens.
When the process stops, the SDK settles with the platform by itself: it delivers what is
buffered, then returns the allowance units it holds. On a generic host (ASP.NET Core, the Azure
Functions isolated worker, a worker service) AddSidubLicensing() registers a hosted service that
does it once every other hosted service has stopped, after the web server has drained; it uses
IHostedLifecycleService.StoppedAsync, which a Microsoft.Extensions.Hosting 8.0 or later host
invokes. On an older host, and with no host at all, the same happens when the service provider is
disposed, and on process exit, each bounded to 5 seconds. It never throws, and there is nothing to
wire.
FlushAsync delivers everything buffered now and returns when it is delivered, for the moments
you want a report out before the process stops:
var buffer = app.Services.GetRequiredService<LicensingConsumptionBuffer>();await buffer.FlushAsync(cancellationToken);A flush already running is awaited first. An aggregate the service refuses outright (a 4xx other
than 408 and 429) is dropped and logged as CONSUMPTION-REFUSED; one that fails transiently stays
buffered and is retried with backoff, up to MaxRetryBackoffMs between flushes. The buffer is
capped at MaxPendingAggregates; a drop is logged as CONSUMPTION-BUFFER-FULL.