.NET API reference

Reference for the SoftActivate.Sdk NuGet package — assembly SWS.dll, namespace SWS.Licensing (.NET 8; one assembly for C# and VB.NET). Generated from the assembly's XML documentation by scripts/refresh-api-docs.mjs — do not edit by hand. Start with LicensingClient; the quickstart shows the canonical usage.

DeviceFingerprint

Collects a fingerprint of the current machine. Feature sources and weights mirror the native SDK so a license activated by either binding validates with the other on the same hardware.

Method	Description
`Collect`	Builds the current device's fingerprint.

Fingerprint

A device fingerprint: a set of weighted, one-way-hashed hardware features. Raw hardware identifiers are never stored or transmitted — each feature value is a PBKDF2-HMAC-SHA256 digest (see the protocol specification, §4).

Method	Description
`#ctor(String)`	Parses a fingerprint from its wire JSON. Values are treated as already hashed.
`AddFeature(String, String, Int32)`	Adds a raw feature value; it is hashed (salted by `type`) before storage.
`Create(String)`	Creates an empty fingerprint of the given type (e.g. "device").
`Matches(Fingerprint)`	True when this fingerprint identifies the same machine as `other`.
`ToJson`	Serializes to the wire JSON shape the licensing service expects.

FingerprintMatcher

The server's hardware-ID matching algorithm, replicated exactly (see the native SDK's fingerprint_matcher and the server's fingerprint-service.js). Two fingerprints identify the same machine when their canonical-digest sets intersect. Pinned by the shared parity vectors so no implementation drifts.

Method	Description
`BuildCanonicalDigests(Fingerprint, Int32)`	Canonical digests in server enumeration order, capped like the server.

License

A validated license: the private key + certificate chain persisted between runs. Serialize it to a file after activation/renewal and load it on start.

Property	Description
`EffectiveDate`	License start date (certificate notBefore), UTC.
`ExpirationDate`	License expiration (certificate notAfter), UTC.
`IsSandbox`	True when this license was issued for a SANDBOX (evaluation) tenant — carried as an issuer-added certificate attribute (additive since server Subplan XT-5a); false for live licenses and licenses issued before the marker existed.
`Issuer`	Issuing domain.
`LicenseId`	License id (first 16 bytes of sha256(license key), hex).
`Metadata`	The license metadata: the full JSON text of the metadata authored on the license template in the console, embedded in the license by the issuing server. Null when the license carries none (no metadata on the template, or a certificate issued before metadata embedding existed). Refreshed at each (re)activation; offline certificates hold the metadata current at issue time.
`Scope`	The license scope: the full JSON text of the scope attribute stamped into the license by the issuing server ({"sku_id": ...}; {} for a product-unbound license), or the requesting client's own scope on certificates issued before servers became the scope authority. Null when the license carries no scope attribute.
`TimestampDate`	The verified token's genTime; null unless `Verified`.
`TimestampStatus`	RFC 3161 timestamp-countersignature state of the LAST validation pass — which validation rung applied (PROTOCOL.md §3.1). `NotPresent` before any validation.
`VendorId`	Vendor id the license was issued for.

Method	Description
`GetMetadataValue(String)`	One metadata value by hierarchical path — same path semantics as `GetScopeValue`.
`GetScopeValue(String)`	One scope value by hierarchical path (e.g. "sku_id", "entitlements.tier", "items.0"): dot-separated object members, non-negative integer segments index arrays. A string value is returned as its exact content; other values as their JSON text. Null when the path is absent, the scope is missing, or the scope is not a JSON object.
`Parse(String)`	Loads a license from its serialized form.
`Serialize`	The serialized license (private key + chain). Persist this verbatim.

LicenseStatus

Outcome of a license validation. Values mirror the native SDK's SWS_LICENSE_STATUS_* codes and the protocol specification.

LicenseValidationResult

Outcome of ValidateLicenseAsync.

Property	Description
`IsValid`	True iff `Status` is `Valid`.
`Status`	The validation status.
`StatusMessage`	Extra detail for the status — notably the subscription state when `Status` is `PaymentRequired`.
`UpdatedLicense`	A newly acquired or renewed license, when validation produced one; otherwise null. Persist it (via `Serialize`) when present.

LicensingClient

Client for the SoftActivate Licensing service. Fully managed — no native dependency. Behavior follows the normative protocol specification and matches the native C++ SDK.

Property	Description
`LicenseKey`	The customer's license key. Required.
`TrustedDomain`	The domain the license chain is pinned to (ca.<domain>). Defaults to the endpoint host; override when the endpoint is on a subdomain of the pinned domain.
`VendorId`	The vendor id the license key belongs to. Required.

Method	Description
`#ctor(String, HttpClient)`	Creates a client with a caller-supplied `HttpClient` (e.g. for custom TLS trust).
`#ctor(String)`	Creates a client for the given licensing endpoint.
`AddTrustedRoot(String)`	Adds one or more trusted deployment roots (concatenated PEM CA certificates) to the anchor list consulted before the standard vroot validation. Optional: only relevant when validating against a self-hosted licensing server whose chains anchor at a private deployment CA; against the hosted service nothing needs configuring. Every certificate must be CA-shaped (basicConstraints CA:true).
`AddTrustedRootFile(String)`	Same as `AddTrustedRoot`, reading the PEM from a file.
`CreateOfflineActivationRequest`	Offline activation, step 1 of 2 (for devices without internet access): generates this device's key pair and the request file the customer emails to the vendor. `RequestFile` is the file to email — the device's certificate signing request preceded by version and License-Key header lines (see PROTOCOL.md §"Offline activation"). `PendingPrivateKey` must be persisted LOCALLY (never emailed) until the reply certificate arrives, then passed to `ImportOfflineActivationResponse`. Requires `VendorId` and `LicenseKey`; performs no network I/O.
`DeactivateLicenseAsync(CancellationToken)`	Releases this machine's seat so the license can be activated elsewhere. Requires `VendorId` and `LicenseKey`.
`ImportOfflineActivationResponse(String, String)`	Offline activation, step 2 of 2: merges the certificate chain the vendor emailed back with the pending private key persisted at export time into a standard `License` (the same serialized form online activation produces — persist `Serialize`'s output). Structural checks only: the response's leaf public key must match the pending key, otherwise the export was re-run after emailing or the wrong file came back. Validate the result with the normal `ValidateLicenseAsync` ladder — a fresh offline certificate validates without any network access.
`SetFingerprintProvider(Fingerprint)`	Overrides how the current-device fingerprint is obtained (testing/platform seam).
`SetProductId(String)`	OPTIONAL product binding: declares the product this application was built for — the product's Reference Id from the console's Products page. When set, every certificate request declares it (a key for a different product is refused at activation, before a seat is consumed) and validation fails a certificate stamped for a different product with `BadProduct`. Never calling this keeps the unbound behavior exactly as before; a null or empty product id throws — not calling is the only unbound state.
`ValidateLicenseAsync(License, CancellationToken)`	Validates `license` for this device, silently re-activating (renewing) when it is missing or expired. Pass null to activate for the first time.

OfflineActivationRequest

The two artifacts of an offline-activation export (see CreateOfflineActivationRequest): the request file the customer emails to the vendor, and the pending private key that never leaves the device. The pending key is this device's identity — the reply certificate is useless without it, and it must be persisted locally until the reply is imported.

Property	Description
`PendingPrivateKey`	The device's private key (PKCS#8 PEM). Persist locally; never email.
`RequestFile`	The file to email to the vendor's support address: the device's certificate signing request (PEM) preceded by version and License-Key header lines.

SwsArgumentException

A required argument or client configuration was missing or invalid.

SwsException

Base type for errors raised by the SoftActivate licensing SDK.

SwsNoTrustedRootException

Reserved: not thrown by current releases. Historically raised when license validation ran without a trusted deployment root configured; trusted roots are now an optional capability (see AddTrustedRoot).

SwsServerException

The licensing service returned an error response.

Property	Description
`StatusCode`	HTTP status code returned by the service.

SwsTrustedRootVendorMismatchException

Reserved: not thrown by current releases. Historically raised when every configured deployment root's vendor-id SAN label belonged to a different vendor than the configured VendorId.

TimestampStatus

RFC 3161 timestamp-countersignature state of a license's last validation pass (PROTOCOL.md §3.1 — which validation rung applied).