The PLUSManagedGui samples are similar to the PLUSManaged samples (which you should review if your application does not use a dialog/form based interface). However, in addition to integrating with PLUSManaged, these samples also integrate with PLUSManagedGui, which is a component that includes a graphical user interface (GUI) for licensing.
The following screenshots show the main activation dialog and a manual request when activating through another computer's Internet connection:
Here are some of the features and highlights to note about the PLUSManagedGui sample applications:
Many of the source code comments begin with TODO and IMPORTANT. It is very important that you review each of these comments in any and all files you copy into your application. Each of these comments indicates an area where you need to make an informed decision about how the application should behave and react in certain scenarios. Disregarding these comments can lead to undesirable behaviors in your application.
The %PUBLIC%\Documents\SoftwareKey\Protection PLUS 5\Samples directory can be opened by running Protection PLUS 5 SDK from your start menu/screen, and clicking on the Protection PLUS 5 SDK Samples link. This directory contains all of the files and folders listed below, as well as several solution files (one for each supported version of Visual Studio). Each solution is configured with the sample projects that are designed for the corresponding version of Visual Studio, and the projects are organized by the underling framework and language used to develop each sample application. For example, any C# applications that use System.Windows.Forms dialogs are located in the CSharp\Windows.Forms solution folder (in the Solution Explorer pane/tab).
A summary of the samples included is provided below.
| Name | Project Locations | Description |
|---|---|---|
| NetworkFloatingSemaphore | CSharp\Windows.Forms\ PLUSManagedGui_NetworkFloatingSemaphore VB.NET\Windows.Forms\ PLUSManagedGui_NetworkFloatingSemaphore |
Shows how you can use semaphore files (or files locked to a running instance of your application) on a Windows (SMB) share to limit the number of users or instances of your application on a network. |
| ReadOnlyLicense | CSharp\Windows.Forms\ PLUSManagedGui_ReadOnlyLicense VB.NET\Windows.Forms\ PLUSManagedGui_ReadOnlyLicense |
Shows how you can use a read-only license file for the highest level of security. These samples do not include evaluation licensing, though this is possible to add. |
| SelfSignedLicense | CSharp\Windows.Forms\ PLUSManagedGui_SelfSignedLicense VB.NET\Windows.Forms\ PLUSManagedGui_SelfSignedLicense |
These samples always use a self-signed/writable license file for all licenses. These types of license files provide the highest level of flexibility, as they allow your application to freely modify the license file (even without Internet connectivity). However, using writable/self-signed licenses means the protected application uses key data fully known to it when encrypting license files, which is less secure than read-only licenses (which use key data only partially known to the protected application). |
The PLUSManagedGui samples use a variety of source code files that are common amongst many or all of the sample applications. The source files are summarized below, and each source file contains commenting which documents the source code in great detail. A summary of the shared source code files is provided below.
| Class/Type | File Locations | Description |
|---|---|---|
| MainForm | MainForm.cs, MainForm.Designer.cs, MainForm.vb, MainForm.Designer.vb, MainForm.resx (Has other supporting files.) |
Contains the main form or dialog implementation for the ReadOnlyLicense and SelfSignedLicense sample applications. This dialog is designed to provide a simple way of showing how your applications can interact with the licensing objects. |
| LicenseConfiguration | LicenseConfiguration.cs
LicenseConfiguration.vb |
Contains licensing configuration properties, including settings required for encryption, and settings which define how the application should behave and react in various circumstances. It is very important to review all of the TODO and IMPORTANT comments throughout this source file. This file contains code that requires changes before using it with your application. |
| SampleLicense | SampleLicense.cs
SampleLicense.vb (Has other supporting files.) |
This is a partial class which contains common definitions and methods used for working with and altering licenses. Additional, partial class files are included (such as SampleReadOnlyLicense.cs or SampleSelfSignedLicense.vb) to implement logic specific the corresponding license implementation class. Each sample application project only includes the partial class file relevant to the type of license implemented. |
| SampleLicense | SampleReadOnlyLicense.cs
SampleReadOnlyLicense.vb |
Implements the License class in PLUSManaged and provides an implementation that only uses read-only license files. This implementation includes support for downloadable and volume licenses. |
| SampleLicense | SampleSelfSignedLicense.cs
SampleSelfSignedLicense.vb |
Implements the WritableLicense class in PLUSManaged and provides an implementation that only uses writable/self-signed license files. Since downloadable and volume licenses may only be read-only, this relies on the VolumeLicense class to support these types of licenses. |
| VolumeLicense | VolumeLicense.cs
VolumeLicense.vb |
Implements support for downloadable and volume licenses for samples that use the SelfSignedLicense class for other types of licenses. |
The LicenseConfiguration class contains a variety of settings, many of which are extremely important to change before re-using the sample source code in your applications. These settings are important for security, and many of them control the application's licensing behavior. As noted earlier, many of the source code comments in this file begin with TODO and TODO: IMPORTANT. These comments indicate an area of code or a setting that you need to review and, in many cases, update. These settings are outlined in the table below.
| Setting Name(s) | Description |
|---|---|
| Encryption Settings | |
| EncryptionKey |
This contains the encryption key data, which usually comes from your SOLO Server account. It is very important that you update this to use your account's data before distributing your application! If you are evaluating Protection PLUS 5 SDK, also make sure you update the Encryption Key to a non-expiring key which will no longer have the "_EVALUATION_EXPIRES_2013-10-05_" expiration date at the beginning (the actual date will be different). If you distribute your application with an evaluation key, it will expire and your customers won't be able to use the software. If you have purchased a license for Protection PLUS 5 SDK but your Encryption Key still has an expiration date, please contact us. Additionally, it is important to use the correct key store in this property. In most cases, your desktop applications should use the user key store, while other types of applications, such as services and web applications/services, should typically use the machine key store. |
| ManualActionIV, ManualActionKey |
When using PLUSManagedGui, you can configure the component (at design time or run time) to allow one or more actions (such as activation, deactivation, and refresh) to be done manually. This enables your customers to leverage another device's Internet connection to manually activate a system which is not connected to the Internet. When using this functionality, it is important to encrypt the data being used in the requests when saving it for later use (so the user can close the application, and complete the request later), and these properties serve as the key used to encrypt this data. When reviewing the LicenseConfiguration class, the source code contains comments above this property that includes sample code which shows how to generate a new key. Each application you protect should have its own, unique key for this property. |
| RegKey2Seed, TriggerCodeSeed |
When adding support for trigger codes to your application, it is very important that these values are updated to contain values that are unique to each application you protect. When using SOLO Server, these values must also match the corresponding values in your Product Option(s) that are configured for the given application. The RegKey2Seed must contain a value between 1 and 255, while the TriggerCodeSeed must contain a value between 1 and 65535. |
| Application & Product Settings | |
| Application Directory | Gets the absolute path to the directory in which the application (executable file) is located. This property is present as a convenience, and is used by other properties when storing other files (such as the license file, aliases, etc...) in the same directory as the sample application. |
| ThisProductID | Gets the application's Product ID. This value is typically issued when configuring a product in SOLO Server. However, if you are not using SOLO Server, this should contain a value that is unique to each application you protect. |
| ThisProductVersion | Gets the application's version number. By default, this uses the assembly version of the protected application. This value must contain 4 parts, no longer than 5-digits each (e.g. N.N.N.N, where each N is at least 0, and no larger than 99999). |
| License File & Alias Settings | |
| PATH_REGISTRY_LOCATION | This constant specifies the Windows registry key value (stored under HKEY_CURRENT_USER) that will be used to store the license file path specified with the NetworkFloatingSemaphore samples. When implementing network floating, it is very important to change this key location to something that is unique to each application you protect. |
| Aliases | Gets a list of aliases used with any samples that use writable license files. By default, this stores the aliases in the same directory as the application or license file for convenience. (This makes it easier for you to simulate running your application on a computer for the first time since its easier to delete the license file and aliases this way.) However, it is very important that you pick better locations to hide/obscure these files for your protected applications. Additionally, it is also very important to make sure the locations selected are unique to each application you protect. |
| LicenseFilePath | Gets the path to the application's license file. By default, this file is stored in the application directory for convenience. |
| ManualActionSessionStatePath | When using PLUSManagedGui, you can configure the component (at design time or run time) to allow one or more actions (such as activation, deactivation, and refresh) to be done manually. This enables your customers to leverage another device's Internet connection to manually activate a system which is not connected to the Internet. This property gets the path to the manual action session state file, which is what stores a manual request so it can be completed at a later time. |
| PathRegistryValue | When using the NetworkFloatingSemaphore samples, this gets or sets the registry value that contains the path to the license file and semaphore files. The registry location is defined in the PATH_REGISTRY_LOCATION constant described above. |
| NetworkSemaphorePrefix | When using the NetworkFloatingSemaphore samples, this sets the prefix used for the semaphore file names. So for example, with the default prefix of "sema", the semaphore files created will be named like "sema123.net". |
| Licensing Restrictions & Settings | |
| FreshEvaluationDuration | When using samples that use a writable license file, this specifies the number of days in which a new evaluation period will last. |
| RefreshLicenseAlwaysRequired | Specifies whether or not the protected application will attempt to validate and refresh its license with SOLO Server every time it starts or validates the license. |
| RefreshLicenseAttemptFrequency | Specifies the number of days to wait before attempting to validate and refresh the license with SOLO Server. |
| RefreshLicenseEnabled | This property is present for convenience, and evaluates RefreshLicenseAlwaysRequired, RefreshLicenseAttemptFrequency, and RefreshLicenseRequireFrequency to determine whether or not license refreshes are enabled at all. |
| RefreshLicenseRequireFrequency | Specifies the number of days to wait before requiring the protected application to validate and refresh its license with SOLO Server. |
| RuntimeBackdateThresholdSeconds | The amount of time (in seconds) to allow the system clock to be back-dated during run-time. |
| SystemIdentifierAlgorithms | The system identifier algorithms to use to uniquely identify and authorize a system. The identifiers generated by these algorithms are pivotal for adding copy protection to your applications. |
| TimeLimitedWarningDays | When using an activated time-limited license in the PLUSManagedGui samples, this specifies the number of days to begin warning the user that the license will soon expire. |
| Volume & Downloadable License File Settings | |
| DownloadableLicenseOverwriteWithNewerAllowed | When using downloadable licenses with trigger code activation, this setting determines whether or not your users can update their license file with a newer file from SOLO Server. Allowing this could make it easier to let your customers update their license through SOLO Server's customer portal after renewing a subscription, or updating registration data, for example. |
| DownloadableLicenseOverwriteWithOlderAllowed |
When using downloadable licenses with trigger code activation, this setting determines whether or not your users can update their license file with a older file. While this feature is not typically needed, we do recommend requiring activation when allowing this. |
| DownloadableLicenseOverwriteWithNewerRequiresActivation | When using downloadable licenses with trigger code activation, this setting determines whether or not your protected application will require the user to process a trigger code activation to use a new license file. |
| DownloadableLicenseOverwriteWithOlderRequiresActivation |
When using downloadable licenses with trigger code activation, this setting determines whether or not your protected application will require the user to process a trigger code activation to use an older license file. |
| VolumeLicenseFilePath | In PLUSManagedGui samples that use self-signed (writable) license files, this specifies the path used for volume license files (which are always read-only). |
| VolumeSystemIdentifierAlgorithms | This specifies the system identifier algorithms used for volume licenses which is generally the LicenseIDIdentifierAlgorithm (as the volume license is not authorized for any particular system, by definition). |