Device licensing, in which Synergy .NET applications use a cloud service for licensing, enables you to license applications on Windows servers, desktops, or laptops that don’t have local Synergy licensing or persistent access to a Synergy license server.
Device licensing is supported for Synergy .NET applications running under .NET Framework, .NET Core, or .NET 5 and higher. For information on developing with Synergy .NET, see Synergy .NET Development.
Getting started
| 1. | Contact Synergex to register as a device license subscriber. (This involves designating one or more “license administrators” and “license developers” for your company.) |
| 2. | (License developer access is required for this step and the next.) Go to the Licenses area of the Synergex Resource Center, log in, and click the Manage Device Licenses button. Then, select the Create New App button. This adds a new device application to the list and creates a “development” license block for internal testing purposes. (An email containing the GUID and public key for the new application, as well as the default token/password, will be sent to all license developers for your company.) |
| 3. | Edit the device application (in the Resource Center) to add a description. (Although this is not required, we highly recommend it if you have more than one application, so you can easily tell them apart.) |
| 4. | Code your application to support device licensing by implementing the device license interface. (See Implementing device licensing and Synergex.SynergyDE.DeviceLicensing.ISynergyDeviceCallback.) |
You can handle device activation in one of the following ways:
- At the start of your application, you can prompt the user for the device license credentials and pass them to the Synergy device runtime.
- Alternatively, you can retrieve those credentials from your server as part of your application log-in process, and when that is complete, pass them to the Synergy device runtime.
| 5. | Contact Synergex to assist you with the testing of your device-licensed application following a detailed device licensing test plan. Coordinated testing with Synergex allows you to test both success and failure scenarios. |
| 6. | When you are ready to deploy your application, contact your Synergex account manager to order a license block, which enables you to license a specific number of devices. You will receive a token and password (one per license block) that is used to activate each device in the block. |
| 7. | Manage licenses and passwords as needed. (License admin access is required for these tasks.) From the Licenses area of the Synergex Resource Center, you can view license block information, modify passwords or add new token/password combinations, transfer licenses from one device to another, deactivate lost or stolen devices, or revoke entire license blocks (e.g., for nonpayment). You can also associate user data with a license block and use that to control application- or customer-specific behavior. |
|
The end users of your device-licensed application must accept the Synergy/DE Product License Agreement terms and conditions. When you register as a device license subscriber, you will receive further instruction regarding an addition you should make to your application’s license agreement. |
How device licensing works
The first time an end user runs your application on a device, the application attempts to activate the license via one of the two methods in step 4 above. The Synergy device runtime then contacts the Synergy device license service, which assigns a unique identifier to the device and activates it by associating it with the license block for those credentials. The device is granted 30 days of authorization.
If the initial activation fails, the device is put into a seven-day grace period, during which time the user will be able to run the application. However, if the device is not successfully activated by the eighth day, subsequent attempts to run the application will fail. Possible reasons for initial activation to fail include an invalid token/password, a full license block, an expired license block, or a duplicate device description.
Once a device is activated, each attempt to run the application will check the number of days of authorization remaining. If it is within 7 days of authorization expiration (or subscription expiration), the runtime will attempt to synchronize the license information with the server. If this is successful, the device is granted another 30 days of authorization. If the device is expired (i.e., 0 days of authorization remain, or the subscription has expired), and this synchronization fails (e.g., because there is no internet connectivity), the device will be given a 24-hour grace period during which it must successfully contact the server in order to get another 30 days of authorization. If it is unable to do so within 24 hours, subsequent attempts to run the application will fail.
We recommend that your application be coded to perform regular synchronizations with the device license service at a time when it is likely to have internet connectivity. You won’t want it to synchronize every day, but perhaps you could establish the frequency relative to the expiration date. For example, if it has been 20 or more days since last contact, the application could perform a synchronization. This information can be obtained using GetLicenseInfo.
A device can also be put into “forced expiration,” where the number of authorization days is set to 0. This occurs on the first successful synchronization following either a deactivation of the device or the revoking of a license block via the device license management website.
Before transferring a license or uninstalling a device application, we strongly recommend that you first deactivate the device license. You can code a feature in your application that deactivates a device by calling DeviceLicensing.Deactivate. The Deactivate method clears the local license information stored on the device and frees up a slot in the license block.
|
Since license information is application specific, you will need to deactivate the device for each device-licensed application installed. |
A device also needs to be deactivated if it is lost, stolen, discarded, or rendered inoperable, or if the device owner has left the company and taken the device. In these cases, since the device is no longer accessible, you must either use the device license management website or contact Synergex to deactivate the device. You will need to provide the license block information as well as the unique device description.
|
We recommend you code a feature in your application that allows you to display the token and device description (using DeviceLicensing.GetLicenseInfo) so you can easily identify devices and manage them. |
Transferring a license
If a license needs to be transferred from one device to another (e.g., when upgrading to a newer model), you must first deactivate the device license. See Deactivating a device above. Once a slot is freed up in the license block, the license can be activated on the new device.
Uninstalling your application
On Windows servers, device licensing is per user. On Windows desktops, laptops, and tablets, device licensing is per machine/device. In both cases, local license information is stored in a file.
Prior to uninstalling a device-licensed application, you must deactivate the device. This clears the local license information and updates the cloud device license service. (On per-user platforms, you do not need to do this if you plan to subsequently reinstall the application.) See Deactivating a device above.
Implementing device licensing
|
|
Synergex provides code samples that demonstrate recommended callback implementations. For an example implementation of device licensing, see WPFDeviceLicense, available from Synergy CodeExchange in the Synergex Resource Center. |
| 1. | Write a Synergy .NET assembly that imports the Synergex.SynergyDE.DeviceLicensing namespace and contains a class that implements the ISynergyDeviceCallback interface. (See Synergex.SynergyDE.DeviceLicensing.ISynergyDeviceCallback for more information and an example.) This class must contain each of the following methods: |
- An Init method that should be coded to call the DeviceLicensing.GetDeviceGUID() method. (See GetDeviceGUID.)
- An ActivationDialog method that should be coded to pass the token and password associated with a license block, as well as a unique device description, to the DeviceLicensing.Activate() method. Typically the method will prompt the device end user for this information but it can also be used in conjunction with your application log-in process. (See Activate.)
- A Synchronize method that should be coded to call the DeviceLicensing.Synchronize(false) method. (See Synchronize.)
The Synergex.SynergyDE.DeviceLicensing namespace that you imported also contains the DeviceLicensing class, which includes several methods that you can use to activate or deactivate a device, request a unique device identifier from the device license service, force license synchronization with the device license service, or retrieve local device license information (such as the license expiration date). Some of these routines must be called at specific times; others can be called at your discretion. See Synergex.SynergyDE.DeviceLicensing.DeviceLicensing for more information.
| 2. | Add the SynergyDeviceLicenseAttribute attribute to the code for the assembly from step 1. The SynergyDeviceLicenseAttribute attribute supports the following property values: |
- PublicKey - (required) The public key you received from the Synergex Resource Center when you created the device application. (string)
- AppGUID - (required) The GUID you received from the Synergex Resource Center when you created the device application. (string)
- Class - (required) The name of the class from the assembly in step 1. The Synergy device runtime will use this class when calling back into your application. (System.Type)
For example,
{assembly:SynergyDeviceLicenseAttribute(PublicKey="MyPublicKey",
AppGUID="MyGuid999", Class=^typeof(MyNamespace.myClass))}
| 3. | In the Visual Studio project for the assembly from the previous steps, select the "Enable Device Licensing" option on the Compile page of project properties. (See Compile page of Visual Studio project properties (Synergy .NET) for more information.) Do not use this option for any other project in the Visual Studio solution that contains this project. |
| 4. | On Windows servers, desktops, laptops, or tablets, add a call to DeviceLicensing.WaitForLicense at the beginning of your application. This prevents the application user interface from appearing prior to license enforcement. (If you are using an application log-in, you don’t need to do this because you are already suspending the application from proceeding until successful log-in.) |
| 5. | Compile your Synergy .NET assembly (from step 2) using the “Enable device licensing” option on the Compile page of project properties (in Visual Studio). |
| 6. | If your main routine is non-Synergy .NET, call Synergex.SynergyDE.SysRoutines.dscrdeviceinit() at the start of your application to ensure that Synergy is licensed immediately, rather than waiting for the first Synergy routine to be invoked (which could be minutes after application launch). |
When your application (assembly) starts up, it will automatically load the Synergy device license subsystem, which attempts to initialize and then activate the device by invoking the necessary callbacks. Once the device is activated, the end user can access the application as long as the device license subscription is valid.
Troubleshooting
To help troubleshoot device licensing problems, we recommend that you include a feature in your application that calls DeviceLicensing.GetLicenseInfo() to obtain local license information. You can then submit the LicenseInfo.DebugInfo value (which is encrypted) to Synergex for assistance.
Once Synergex has received this information, they may direct the user to clear the local license information. Therefore, we recommend that your application also include a feature that calls DeviceLicensing.Deactivate(), to simplify this process.
