Skip to content

.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.

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.
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.

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.

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.

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.

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.