Slascone.Client 2.2.17

Contents

• Overview
• Examples on GitHub
• API endpoints
• API responses and error handling
• Convenience features
• Using Slascone Client in your application
• Release notes

For more information, see the SLASCONE website, the Help Center, and the API Test Center.

Slascone.Client

Overview

A .NET Standard 2.0 client for the SLASCONE API.

This package provides strongly typed access to the SLASCONE software licensing and analytics solution and includes higher-level helper functions for common integration scenarios.

In addition to basic API access, the library supports digital signature verification, environment detection, device fingerprinting, and offline license handling. This makes it easier to implement secure license validation, support different deployment environments, and handle temporary connectivity loss.

The library is particularly useful for applications that require (temporary) offline support.

Examples on GitHub

You can find example applications using the Slascone.Client library on our Slascone GitHub repository. These samples show how to integrate the client into .NET projects, including WPF and C# console apps, and demonstrate key features such as license activation, heartbeat handling, and offline license support.

• https://github.com/SLASCONE/SLASCONE-demo-wpf-nuget
• https://github.com/SLASCONE/SLASCONE-demo-csharp-nuget

API endpoints

Corresponding to the controllers of the SLASCONE RestAPI, the Slascone.Client library provides a set of interfaces that represent the various API controllers. The Swagger UI, which provides an overview of the controllers and all endpoints, is available at the URL https://api365.slascone.com/swagger.

The main entry point is the ISlasconeClientV2 interface, which exposes a set of strongly-typed API controller clients for all major SLASCONE features, including license management, provisioning, customer and product management, and more.

API responses and error handling

Every call to a Slascone.Client method returns an ApiResponse (or ApiResponse<T>) object. Use the StatusCode property to determine the outcome of the call:

• Successful call (StatusCode == 200): The request was processed successfully. For methods that return data, the result is available in the Result property of the generic ApiResponse<T>. Example:

var response = await slasconeClient.Provisioning.AddHeartbeatAsync(heartbeatDto);

if (response.StatusCode == 200)
{
    // Access the result
    var licenseInfo = response.Result;
}

• Functional/logical error (StatusCode == 409): The SLASCONE backend understood the request but rejected it due to a business rule violation (e.g., an expired license, an unknown license key, or a limit being exceeded). In this case the Error property contains an ErrorResultObjects instance with a numeric Id identifying the specific error, a human-readable Message, and an optional Help text. You can use the Id to programmatically react to specific error conditions. You can find a list of the possible error IDs and their meaning on the Swagger UI at the URL https://api365.slascone.com/swagger for the respective endpoint. Example:

if (response.StatusCode == 409)
{
    Console.WriteLine($"Error {response.Error.Id}: {response.Error.Message}");
    
    // React to a specific error, e.g., expired license
    if (response.Error.Id == 1001)
    {
        // Handle expired license scenario
    }
}

• Technical/server error (StatusCode in the 400 or 500 range, but not 409): These indicate technical problems such as authentication failures (401), bad requests (400), or internal server errors (500). The Message property contains a description of the error, and the ApiException property provides the underlying ApiException with additional details such as the raw Response body and HTTP Headers. For rate-limited responses (429/503/504), the ApiException.Headers may include a Retry-After value. Example:

if (response.StatusCode >= 400 && response.StatusCode != 409)
{
    Console.WriteLine($"Technical error (HTTP {response.StatusCode}): {response.Message}");
    
    if (response.ApiException != null)
    {
        // Access the raw response body
        Console.WriteLine($"Response: {response.ApiException.Response}");
    }
}

• Network/connectivity error (StatusCode == -1): If the client cannot reach the SLASCONE backend at all (e.g., due to DNS resolution failure, connection timeout, or other network issues), the StatusCode is set to -1 and the ApiException property contains an ApiException whose InnerException is the original network-related exception (typically an HttpRequestException). You can inspect the InnerException to distinguish a network failure from a server-side 400 response. Example:

if (response.StatusCode == -1 && response.ApiException?.InnerException is HttpRequestException httpEx)
{
    Console.WriteLine($"Network error: {httpEx.Message}");
    // Consider retry logic or falling back to offline license validation
}

Please consult also our support article on ERROR HANDLING especially for aspects e.g. how to implement retry and fallback strategies in case of rate limits or network issues.

Class definitions for API responses and exceptions

The class definitions of ApiResponse, ApiResponse<T>, ApiException, and ApiException<T> are as follows:

    public class ApiResponse
    {
        /// <summary>
        /// It holds the information if <c>StatusCode</c> is 409
        /// </summary>
        public ErrorResultObjects Error;

        /// <summary>
        /// Expected values: 200, 400, 401, 409 or 500
        /// </summary>
        public int StatusCode { get; set; }

        /// <summary>
        /// It holds the information if StatusCode is 400, 401 or 500
        /// </summary>
        public string Message { get; set; }

        /// <summary>
        /// It holds the information if StatusCode is 400, 401 or 500
        /// </summary>
        public ApiException ApiException { get; set; }
	}

    public class ApiResponse<T> : ApiResponse
    {
        /// <summary>
        /// It holds the information if <c>StatusCode</c> is 200
        /// </summary>
        public T Result { get; set; }
    }

    public partial class ApiException : System.Exception
    {
        public int StatusCode { get; private set; }
        public string Response { get; private set; }
        public IReadOnlyDictionary<string, System.Collections.Generic.IEnumerable<string>> Headers { get; private set; }
    }

    public partial class ApiException<TResult> : ApiException
    {
        public TResult Result { get; private set; }
    }

Convenience features

Some of the most utilized convenience functions include:

• Digital Signature Verification: Methods like IsFileSignatureValid allow you to verify the authenticity and integrity of license or activation files using asymmetric or symmetric cryptography.
• Offline License Handling: Functions such as GetOfflineLicense enable applications to read and validate license information even when temporarily disconnected from the SLASCONE backend.
• Environment Detection: Utilities in LinuxDeviceInfos and WindowsDeviceInfos help detect if the application is running in a Docker container, virtual machine, or cloud environment by checking for specific files or system properties.
• Unique Client ID Retrieval: The client provides access to various hardware and system identifiers (e.g., machine ID, MAC addresses, DMI product UUID) to generate or retrieve a unique device fingerprint, which is essential for license assignment and tracking.
• System Information Logging: Methods like LogDeviceInfos collect and format detailed device information for diagnostics, support, or analytics purposes.
• HTTP Header Management: The client exposes methods to set, add, or retrieve custom HTTP headers, supporting advanced integration scenarios and user tracking.
• Version number compliance check to check the compliance of an offline license file with the current version of the client software.
• Device Info Helpers: Platform-specific classes in the DeviceInfos namespace provide access to hardware and system identifiers (e.g., WMI UUIDs, Linux machine IDs, MAC addresses), virtualization detection, and cloud environment detection (AWS EC2, Azure VM) for generating a unique client_id for license activations.

These convenience functions are accessible through the ISlasconeClientV2 interface and its platform-specific helpers, making it easy to integrate robust licensing and device management features into your application.

For a detailed technical reference of all convenience methods, including method signatures, parameters, and return values, see the Convenience Features.

For a detailed technical reference of all device info features, including device identification, virtualization detection, and cloud environment detection, see the Device Info Features.

Handling of temporary offline scenarios

License information that is retrieved from the SLASCONE backend is stored in a temporary offline license file. In case the application is not able to connect to the SLASCONE backend, e.g. due to network issues, the application can use the temporary offline license file to validate the license. The temporary offline license file is stored in the application data folder specified by SetAppDataFolder.

Custom logic for storing and retrieving license information for offline use

The ITemporaryOfflineDataStorageStrategy interface defines methods for writing and reading license information and its associated signature, as well as managing session data. Instead of using the default implementation of the temporary offline license handler that stores data in the application data folder, you can implement the ITemporaryOfflineDataStorageStrategy interface to provide custom logic for storing and retrieving license information for offline use. Use a custom implementation if you don't want to store the data in the local file system but e.g. in a database.

Set the custom implementation of the ITemporaryOfflineDataStorageStrategy interface using the SetOfflineDataStorageStrategy method of the ISlasconeClientV2 interface. Do not use the methods SetAppDataFolder, SetTempOfflineLicenseFilenames, and SetTempOfflineSessionFilename when using a custom implementation of the ITemporaryOfflineDataStorageStrategy interface, as these methods are only applicable for the default implementation that stores data in the application data folder.

    /// <summary>
    /// Defines a strategy for temporarily storing offline data.
    /// </summary>
    public interface ITemporaryOfflineDataStorageStrategy
    {
        /// <summary>
        /// Writes license information and its associated signature.
        /// </summary>
        /// <param name="licenseInfo">A byte array containing the license information to write.</param>
        /// <param name="signature">A string representing the signature for the license information.</param>
        void WriteLicenseInfo(byte[] licenseInfo, string signature);

        /// <summary>
        /// Retrieves the license information and its associated signature.
        /// </summary>
        /// <returns>A tuple containing the license information as a byte array and the signature as a string.</returns>
        (byte[] LicenseInfo, string Signature) ReadLicenseInfo();

        /// <summary>
        /// Writes session data to the storage.
        /// </summary>
        /// <param name="sessionData"></param>
        void WriteSessionData(string sessionData);

        /// <summary>
        /// Retrieves the session data from the storage.
        /// </summary>
        /// <returns></returns>
        string ReadSessionData();

        /// <summary>
        /// Removes the session data from the storage, effectively clearing any stored session information.
        /// </summary>
        void RemoveSessionData();

        /// <summary>
        /// Appends lines of text to a file associated with the specified type name.
        /// </summary>
        /// <param name="typeName">The name of the type associated with the file.</param>
        /// <param name="lines">The lines of text to append.</param>
        void AppendLines(string typeName, IEnumerable<string> lines);

        /// <summary>
        /// Returns an enumerable collection of lines associated with the specified type name.
        /// </summary>
        /// <param name="typeName">The name of the type for which to retrieve lines.</param>
        /// <returns>An enumerable collection of strings representing the lines.</returns>
        IEnumerable<string> ReadLines(string typeName);

        /// <summary>
        /// Clears the lines associated with the specified type name, effectively removing any stored data for that type.
        /// </summary>
        /// <param name="typeName">The name of the type for which to clear lines.</param>
        void ClearLines(string typeName);
    }

Signature verification of offline license files

If the license validation is supposed to be done offline, the Slascone.Client library provides methods to verify the digital signature of the license file to ensure its integrity and authenticity.

Using Slascone Client in your application

Instantiation of a Slascone.Client instance

To create an instance of the client, use the SlasconeClientV2Factory class, which provides static methods to build and configure an ISlasconeClientV2 implementation. The client supports advanced configuration options such as custom HTTP headers, certificate validation, offline license handling, and more.

	string ApiBaseUrl = "https://api.slascone.com";
	Guid IsvId = Guid.Parse("2af5fe02-6207-4214-946e-b00ac5309f53"); 
	string ProvisioningKey = "your-provisioning-key";

	_slasconeClientV2 =
		SlasconeClientV2Factory.BuildClient(ApiBaseUrl, IsvId, ProvisioningKey);

Key components:

• ISlasconeClientV2: The main interface aggregating all API controller clients and configuration methods.
• SlasconeClientV2Factory: Factory class for creating and initializing ISlasconeClientV2 instances.

Example for creating a license heartbeat:

	var heartbeatDto = new AddHeartbeatDto	
	{
		Product_id = Guid.Parse("your-product-id"),
		Client_id = clientId,
		Token_key = GetTokenKeyFromTemporaryOfflineLicense(),
		User_id = _authenticationService.IsSignedIn ? _authenticationService.Email : null,
		Software_version = SoftwareVersion,
		Operating_system = OperatingSystem
	};
	var result = await _slasconeClientV2.Provisioning.AddHeartbeatAsync(heartbeatDto);

Configuration

The base URL of the SLASCONE API, your ISV ID, and your provisioning key are provided during client construction via SlasconeClientV2Factory.BuildClient. Beyond these essentials, the client offers configuration methods in the following areas:

• Authentication: Switch between provisioning key, admin key, or JWT bearer token authentication using SetProvisioningKey, SetAdminKey, or SetBearer.

• Signature verification: Control how API response signatures are verified. Use SetSignatureValidationMode to choose none, symmetric, or asymmetric verification. For asymmetric mode, provide the public key via SetSignatureCertificate, SetSignaturePublicKeyXml, or SetSignaturePublicKey. For symmetric mode, use SetSignatureSymmetricKey.

• Offline data storage: Enable temporary offline license storage by setting a local folder with SetAppDataFolder, or provide a completely custom storage implementation via SetOfflineDataStorageStrategy. When using the default file-based strategy, you can optionally customize the offline filenames with SetTempOfflineLicenseFilenames and SetTempOfflineSessionFilename.

• HTTP settings: Configure the request timeout with SetHttpClientTimeout (default: 100 seconds). Manage custom HTTP headers with SetHttpRequestHeader, AddHttpRequestHeader, and TryGetHttpRequestHeader. Use SetLastModifiedByHeader to identify the requesting user in backend history entries. Enable HTTPS certificate chain diagnostics with SetCheckHttpsCertificate.

All configuration methods return the ISlasconeClientV2 instance, allowing fluent chaining (e.g., client.SetAppDataFolder(path).SetSignatureValidationMode(2).SetSignatureCertificate(cert)).

For a detailed technical reference of all configuration methods, including method signatures, parameters, and return values, see the Configuration Methods.

Release notes

2.2.17

• Support for API Compatibility level 220: Changed the Value property of the ProvisioningLimitationDto class from int to int? (nullable int) to allow for limitations that do not have a specific numeric value, such as boolean limitations or unlimited usage. More about the SLASCONE compatibility levels here.

2.1.1071

• Added missing member ExpirationDateUtc to ProvisioningFeatureXmlDto class for XML license files.

2.1.1060

• Changed status code for network/connectivity errors to -1. This allows distinguishing between actual HTTP 400 responses from the server and network-related issues where the client cannot reach the server at all.

2.1.1057

• Improved error response

2.1.1051

• Fixed Error 409 handling

2.1.1047

• Added Http response headers to ApiException in order to have access to "Retry-After" header for better handling of rate limits.

2.1.1041

• Defines the ITemporaryOfflineDataStorageStrategy interface for handling temporary offline license files, allowing applications to implement custom logic for storing and retrieving license information for offline use.

2.1.1011

• Replay Attack Protection: Enhanced security by implementing nonce-based request verification. When asymmetric signature validation is enabled (SetSignatureValidationMode(2)), the client automatically adds a unique X-Nonce header to each request. The server signs this nonce and returns it in the X-Nonce-Signature response header, which the client verifies to ensure the response is authentic and not a replayed message from a previous session.

2.1.961

• New versions of the ISlasconeLicenseClientV2.GetConsumptionHeartbeatsAsync() with new parameters transaction_id, user_id, and client_id
• New attribute client_name in LicenseInfoDto

2.1.943

• New versions of GetAllCustomersAsync(), GetCustomerTypesAsync(), GetLicenseTypesAsync(), GetAllProductsAsync(), GetAllTemplatesAsync() methods with 'name' parameter
• New DeviceLicenseAssignmentDto property: Suspended_until_utc
• New LicenseFilterDto property: Is_suspended_token
• New SessionDto property: Duration
• New TemplateVariableDto property: Is_required
• New CloseAllSessions() endpoint in Provisioning controller
• Updated dependencies

2.1.917

• Fixed User-Agent header version number

2.1.874:

• Added 'start_date' to license information for online and offline licenses

2.1.847:

• Added value array to analytical heartbeat
• Software shipment: new flag 'is_latest'

2.1.842:

• Offline usage analytics
• Renovate Readme.md; added release notes section and documentation for the Slascone.Client configuration and convenience methods.

2.1.838:
Introduces product controller and start date

• Added product controller
• Added start date