Table of Contents

Installation

Note: You will need a Software Vendor account at elm.evoleap.com to use the elm client API. Contact evoleap to open an account.

The elm client API for .NET is distributed via NuGet.

Install-Package evoleap.Licensing -Pre

Getting started

First, embed your application's product id and version somewhere in your application code. You can get the product id from the elm web portal.

static class Constants
{
    internal static readonly Guid ProductId = new Guid("XXXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX");
    internal static readonly string ProductVersion = "1.0.0.0";
}

Then download the public key file for the product from the elm web portal and load it into your application:

// From a resource string:
var keyFile = PublicKeyFile.Create(Resources.PublicKey);

// From an external file:
var keyFile = PublicKeyFile.ReadFrom(filePath);

Next, get the user's license key. How that happens is up to you, but typically the application would show a window welcoming the user to the app and asking for their license key.

var licenseKey = AskUserForLicenseKey();

Once you have the license key, create an instance of the ControlManager class, passing in the product id and version, public key file, any configuration options, and any saved state.

var controlManager = new ControlManager(
  Constants.ProductId,
  Constants.ProductVersion, 
  keyFile,
  controlStrategy: <strategyObject>,
  savedState: <stateObject>,
  sessionState: <sessionStateObject>);

Next, check the ControlManager.ValidationState.Registered property to determine whether registration is required.

bool shouldRegister;
if (controlManager.ValidationState.Registered) {
  shouldRegister = false;
}
else {
  shouldRegister = true;
}
Note: if your application supports an unregistered grace period, these registration steps are not required until the grace period has expired.

If registration is required, get the instance's identity. The instance's identity is a collection of key-value pairs that uniquely identify the instance in the elm system, and is represented by the InstanceIdentity class. The HardwareBasedInstanceIdentity class provides a helper method for filling an empty InstanceIdentity instance using a standard set of hardware attributes using .NET and Windows APIs.

if (shouldRegister) {

  // Use current hardware info as instance identity:
  var instanceIdentity = await new InstanceIdentity().AddAllHardwareKeysAsync();

  // Or, use custom instance identity
  var instanceIdentity = new InstanceIdentity();
  instanceIdentity.Data.Add("key", new InstanceIdentityValue("value")); // string value
  instanceIdentity.Data.Add("key2", new InstanceIdentityValue(new [] { "value1", "value2" })); // string array value
  ...

Also get the user's registration information and identity. User registration information consists of a user name and email address. Like instance identity, the user's identity is a collection of key-value pairs that uniquely identify the user in the elm system, and is represented by the UserIdentity class. The ActiveDirectoryBasedUserIdentity class provides a factory method for generating a UserIdentity instance from the current Windows user's active directory credentials.

if (shouldRegister) {
  var userInfo = new UserInfo("name", "email");

  // Use current user's Active Directory credentials:
  var userIdentity = await ActiveDirectoryBasedUserIdentity.GetCurrentAsync();

  // Or, use custom user identity
  var userIdentity = new UserIdentity();
  userIdentity.Data.Add("key", "value");
  ...

Next, call the RegisterAsync method to register the current instance of the application with the licensing system. If the current instance is already registered, this call does not contact the server.

  var result = await controlManager.RegisterAsync(licenseKey, userInfo);
  if (!result.Success) {
    // Not registered, deny access or try again.
  }

Once registration succeeds, call the ValidateSessionAsync method to verify that the user is authorized to use the application and start a new session.

var validity = await controlManager.ValidateSessionAsync();
if (validity.IsValid) {
  // Allow access
}
else {
  // Deny access
}

Later, during the application's shutdown process, call the EndSessionAsync method to end the session. A session cannot be restarted once it has ended.

await controlManager.EndSessionAsync();

Concurrent licenses

If your application needs to support concurrent licenses, the application is required to contact the server at regular intervals in order to keep track of how many sessions are active at one time. To support this, the SessionExtensionTimer class can be used to perform a new validation every time a status check is required.

Create an instance of the SessionExtensionTimer class and set up an event handler for the LicenseCheckNecessary event. The handler should call ControlManager.ValidateSessionAsync to extend the session and leave it checked out from the server. To ensure that the LicenseCheckNecessary event is raised at the correct interval, call the SessionExtensionTimer.Update method after every call to ValidateSessionAsync.

var timer = new SessionExtensionTimer();

// initial registration/validation code
...

// Start timer for session extensions
timer.Update(validity);

// set up handler for session extensions
timer.LicenseCheckNecessary += async (s, e) =>
{
    // NOTE: This event is raised on a background (ThreadPool) thread.

    var validity = await controlManager.ValidateSessionAsync();
    timer.Update(validity);
    if (validity.IsValid) {
        // Session successfully extended
    }
    else {
        // Session is no longer valid.  Deny further access to the application.
    }
}

Storing license information

The client API provides full support for remembering registration and validation information across sessions of an application. Storing licensing information is highly recommended, as it reduces the number of calls to the licensing server on application startup and enables the client to detect if the user is tampering with the system clock. However, the data must be stored securely, as third-party modifications of the stored data could allow users access to the application without authorization.

The IValidationState and IValidatedSessionState interfaces define all of the data that must be stored.

Important: The application should update the stored version of the data after any call to a ControlManager method.

// Update stored data after every ControlManager call:

await controlManager.RegisterInstanceAsync();
StoreLicensingData(controlManager);

// Later

await controlManager.ValidateSessionAsync();
StoreLicensingData(controlManager);

// etc.

void StoreLicensingData(ControlManager controlManager)
{
    var data = controlManager.ValidationState;
    SaveDataSomewhere(data);

    // If storing in-progress session state (usually not required for desktop apps)
    var sessionData = controlManager.SessionState;
    SaveSessionDataSomewhere(sessionData);
}

The ControlManager can be initialized with the saved state by passing in a IValidationState object to its constructor:

var controlManager = new ControlManager(productId, licenseKey, keyFile, savedState: <state>, sessionState: <sessionState>);

Components

Introduced in version 3.1 of the elm web API and version 4.0 of the .NET Client API, component licensing provides an additional layer of licensing flexibility within a product. Individual parts of an application ("components") can require additional licensing restrictions, such as tokens or sessions, in order to be accessed. The ControlManager provides a set of methods for managing the licensing of individual components within an application, including querying the status of a component's license requirements and checking out a component.

To query the status of the components configured for the product, call the ControlManager.GetComponentsStatus method: 

var componentsStatus = await controlManager.GetComponentsStatus();

The object returned from this call contains a number of properties that describe the license requirements for each component and the availability of the tokens or sessions required to use each component.

To check out a component to the current session, call the ControlManager.CheckOutComponentsAsync method, passing in the names of the components to check out. The component names are defined in the elm portal. 

var result = await controlManager.CheckOutComponentsAsync("Component1", "Component2");

The object returned from this call is similar to the object returned from the ControlManager.ValidateSessionAsync call; it describes whether the checkout was successful, and if not, why the checkout failed.

Note: Once a component has been checked out, it remains checked out until the session is ended. There is currently no way to check "in" a component before a session is ended.

Offline Checkout

Version 3.2 of the elm web API and version 5.0 of the .NET Client API introduce the ability to checkout concurrent sessions for product licenses and tokens for components for offline use. With these additional APIs, you could enable your users to checkout entitlements in advance of when they would be offline, and therefore unable to validate their sessions. It is important to note that, at this time, the API does not allow the conversion of a currently active session, i.e., one that has been validated by the elm server, into an offline checkout.

Changes

There are additional fields of information in the IValidationState object that need to be persisted. Once sessions or component tokens are checked out, this information needs to be saved to the state object so that the ControlManager can first check for availability of checked out sessions/tokens during initiation of future sessions.

In addition, IValidatedSessionState contains additional information that would inform the API consumer whether the session initiation was performed using an offline checkout rather than by making a call to the web API.

New Calls

There are five new ControlManager calls introduced in version 5.0 of the .NET Client API.