.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.
ActivationError
Why the activation exchange of a validation call failed. Present on Error whenever a first activation, a required renewal or a proactive renewal did not produce a license; null when no exchange failed. Worth logging: it tells an unknown key apart from a network outage.
| Property | Description |
|---|---|
Code |
The service's machine-readable error code (for example license_not_found, vendor_mismatch, account_inactive, license_revoked, context_limit, rate_limited) or, when the failure happened before a usable answer, a client code: network (no answer: connection, DNS, TLS or proxy failure), timeout, bad_response (a success status without a usable license) or client_error (a local failure before or while sending). Empty for an HTTP error that carried no code. |
Exception |
The underlying exception, for logging. |
HttpStatus |
The HTTP status of the licensing service's answer; 0 when no answer was received. |
Message |
The service's message, the start of a non-JSON error body, or the local error's text. |
| Method | Description |
|---|---|
ToString |
A one-line description, e.g. "HTTP 401 license_not_found: no license has this key". |
DeviceFingerprint
Collects a fingerprint of the current machine from several of its hardware characteristics. The native SDK reads the same characteristics, so a license activated with either library validates with the other on the same hardware.
| Method | Description |
|---|---|
Collect |
Builds the current device's fingerprint. |
IsVirtualMachineIdentity(String, String) |
(SDK 1.2.0) Internal support method used by the SDK's virtual machine detection. |
Fingerprint
A device fingerprint: a set of hardware characteristics, each kept only as an irreversible hash. Raw hardware identifiers are never stored or transmitted.
| Property | Description |
|---|---|
Virtualization |
(SDK 1.3.0) The kind of virtual machine this machine runs in, when the SDK recognises it: wsl2 inside Windows Subsystem for Linux 2; null otherwise. The value is sent to the service alongside the fingerprint and never takes part in device matching. |
VirtualMachine |
(SDK 1.2.0) Whether this machine reports itself as a virtual machine; null when unknown. The value is sent to the service alongside the fingerprint and never takes part in device matching; a trial license may refuse new devices that report one. |
| Method | Description |
|---|---|
#ctor(String) |
Parses a fingerprint from its JSON form, as ToJson produces it. Feature values are taken as already hashed. |
AddFeature(String, String, Int32) |
Adds a raw feature value of the given type; it is hashed before it is stored, so the raw value never leaves the machine. |
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 the fingerprint to the JSON form the licensing service expects. |
FingerprintMatcher
Internal support type used by the SDK's device matching. Applications compare fingerprints with Matches instead.
| Method | Description |
|---|---|
BuildCanonicalDigests(Fingerprint, Int32) |
Internal support method used by Match. |
License
A license issued to this device, kept between runs. Serialize it to a file after activation or renewal and load it on start.
| Property | Description |
|---|---|
EffectiveDate |
The license start date, UTC. |
ExpirationDate |
When the license itself ends, UTC: a fixed term's end, a subscription's paid-through date plus its grace period, or this device's trial end. NoExpiration for a license that never ends. |
IsSandbox |
True when this license was issued from a sandbox (evaluation) vendor account; false for live licenses and for licenses issued before the sandbox marker existed. |
Issuer |
Issuing domain. |
IsTrial |
(SDK 1.2.0) True when this license was issued under a trial license: the vendor's trial key, built into the application, under which each device gets its own trial period counted from its first activation, and ExpirationDate is this device's trial end. False for every other license. |
LicenseId |
The license id, derived from the license key. |
Metadata |
The license metadata: the full JSON text of the metadata authored on the license template in the console, written into the license by the issuing service. Null when the license carries none (no metadata on the template, or a license issued before metadata embedding existed). Refreshed at each activation or renewal; offline licenses hold the metadata current when they were issued. |
OfflineExpirationDate |
(SDK 1.4.0) Until when the license keeps validating on this device without reaching the licensing service, UTC; the client renews it online before then. Never later than ExpirationDate. |
Scope |
The license scope, as the JSON text written into the license by the issuing service: {"sku_id": ...} for a license bound to a product, {} for a product-unbound license. Null when the license carries no scope. |
TimestampDate |
The time the license was timestamped; null unless the status is Verified. |
TimestampStatus |
The state of the license's issue-time timestamp, as found by the last validation pass; NotPresent before any validation. Informational only: the timestamp is what keeps a license verifiable years after it was issued, with no action from the application. |
VendorId |
Vendor id the license was issued for. |
| Method | Description |
|---|---|
GetMetadataValue(String) |
One metadata value by hierarchical path, with the 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. Persist this verbatim. |
LicenseStatus
Outcome of a license validation. Values correspond to the native SDK's SWS_LICENSE_STATUS_* codes. New values are only ever appended: treat a value your code does not know as not valid.
LicenseValidationResult
Outcome of ValidateLicenseAsync.
| Property | Description |
|---|---|
Error |
Why the activation exchange of this call failed, when one was attempted and did not produce a license, also when the verdict stayed Valid because a proactive renewal failed. Null when no exchange failed. |
IsValid |
True iff Status is Valid. |
Status |
The validation status. |
StatusMessage |
Extra detail for the status: the subscription state or plan reason when Status is PaymentRequired, the retry hint when it is SeatLimit; "" otherwise. |
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, with no native dependency; it behaves the same as the native C++ SDK, and a license activated with either library validates with the other on the same device.
| Property | Description |
|---|---|
LicenseKey |
The customer's license key. Required. A key typed or pasted with lower-case letters, spaces or missing dashes is stored in its canonical XXXXX-XXXXX-XXXXX-XXXXX-XXXXX form; any other input only loses surrounding whitespace. |
TrustedDomain |
The domain the SDK trusts when validating licenses. Defaults to the endpoint host. For the hosted service, set it to sws.softactivate.com, since the endpoint itself is on the lm. subdomain. |
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 (PEM text, concatenated when there are several) that licenses may be verified against. Optional: only needed when validating against a self-hosted licensing server that issues licenses under its own deployment certificate; against the hosted service nothing needs configuring. Pass the public file of a deployment certificate generated in the console; a certificate that cannot act as a deployment root is rejected with SwsArgumentException. |
AddTrustedRootFile(String) |
Same as AddTrustedRoot, reading the PEM from a file. |
CreateOfflineActivationRequest |
Offline activation, step 1 of 2, for devices without internet access: prepares the request file the customer emails to the vendor, and this device's pending private key. RequestFile is the file to email: a small text file that carries the license key and this device's public identity, and no secrets. PendingPrivateKey must be kept locally (never emailed) until the vendor's reply 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: combines the reply the vendor emailed back with the pending private key saved at step 1 into a License, in the same serialized form online activation produces (persist the output of Serialize). Only the pairing is checked here: the reply must belong to the pending key, otherwise the request was generated again after it was emailed, or the wrong reply file came back, and SwsArgumentException is thrown. Validate the result with ValidateLicenseAsync as usual; a fresh offline license validates without any network access. |
SetFingerprintProvider(Fingerprint) |
Overrides how the current device's fingerprint is obtained, for tests or custom platforms. |
SetProductId(String) |
Optional product binding: declares the product this application was built for, by the product's Reference Id from the console's Products page. When set, every activation request declares it (a key for a different product is refused at activation, before a seat is consumed) and validation reports a license issued for a different product as BadProduct. Not calling this leaves the client unbound; a null or empty product id throws. |
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. When the activation fails, Error says why. |
OfflineActivationRequest
The two parts of an offline-activation request (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 vendor's reply cannot be used without it, so it must be kept locally until the reply is imported.
| Property | Description |
|---|---|
PendingPrivateKey |
The device's private key, as PEM text. Keep it locally; never email it. |
RequestFile |
The file to email to the vendor's support address: a small text file that carries the license key and this device's public identity, and no secrets. |
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 belonged to a different vendor than the configured VendorId.
TimestampStatus
The state of a license's issue-time timestamp, as found by the last validation pass. Informational only: the timestamp is what keeps a license verifiable years after it was issued, with no action from the application.