Welcome to the SoftwarePotential.Configuration.Hardware-<PermutationShortCode> NuGet Package.
IMPORTANT: this package is intended to be used in concert with:
- SoftwarePotential.Licensing-<MyProduct>-<MyVersion> NuGet package (must be installed for the code to compile correctly). See the associated Licensing README for more information.
- SoftwarePotential.Protection-<PermutationShortCode> NuGet package. See the associated Protection README for more information.
Key Constraints and Advantages of this MULTI USER Configuration Package
This package is intended to offer a licensing configuration for an application that needs to manage licenses across multiple user Profiles but where the licenses are tied to a hardware dependent Device ID. In the event that it is not possible to generate a unique DeviceID based on pre-selected hardware properties of the device, then the Device ID will default to that used with the Multi-user configuration.
Apart from the manner in which the Device ID is generated, the Hardware configuration is similar to the MultiUser configuration in that your application and its licenses can be used by multiple Windows users on each target machine. It also means you must write and distribute a separate installer (i.e. an MSI package or similar) to initialize the required license store.
Please note there is no SingleUser equivalent of the Hardware configuration i.e. where an installer is not required to configure the store location.
License Storage Location Base Path
Adding this NuGet package to your application configures the runtime such that licenses are stored in a shared Application Data folder by default i.e. out of the box, the directory used by the code in this package results in a base path such as C:\ProgramData\MyCompany\MyProduct\MyVersion
. You can of course select a different location by ammending the based path appropriately.
The license store needs to be accessible by all users of the application on a given machine. Therefore an explicit store initialization step is needed as part of application deployment (as outlined in License Store Initialization section) ).
Customizing the license store path
Out of the box, the path used is derived from your Company and Product names as supplied to the Software Potential service. This is only intended as a placeholder and you are free to customize the exact names used.
Within the Base Path, this package generates a subdirectory structure for your applications licenses as follows: MyCompany\MyProduct\MyVersion
(Having a subdirectory structure like this is necessary if the base directory is shared among all applications on the machine.)
To change either the base path, or the subdirectory used for your application's license storage area, please refer to the SpAgent.ConfigureLocalStorePath()
method (in SpAgent.Configuration.Local.Customizations.cs
).
See -Customization of SpAgent Storage Configuration for more details on how to modify the Customizations.cs file
License Store Initialization
The shared licensed store needs to be created and initialized by a privileged user (local administrator) during application deployment/installation. The following approaches are possible:
1.1. Using installutil.exe during installation
This package provides an SpAgentInstaller
class (in SpAgent.Configuration.Local.MultiUser.Installer.cs
), which is a .NET Managed Installer class. The installation sequence within SpAgentInstaller
class can be invoked by running installutil.exe command-line utility (provided by .NET Framework SDK or Windows SDK) from Administrator Command Prompt: installutil.exe MyApplication.exe
This command needs to be called from your installer / installation script.
1.2. Employing a command-line installation option in the application
- Add a command-line installation option to your application (e.g.
-install
) - When the commandline option is supplied, have your
Main
method:- call
SpAgentConfiguration.InitializeSharedLicenseStorage()
- exit to allow the rest of the installation to complete (i.e. the application should exit immediately)
- call
- Have your installer / installation script call your application with the installation option:
MyApplication.exe -install
1.3. Using a custom action in a Windows Installer
For an example how to use a custom action in a Windows Installer to initialize a license store, please refer to this sample:
https://github.com/SoftwarePotential/samples/tree/master/Sp.Samples.Agent.WpfApplicationWithInstaller
License Store Verification
We recommend calling the following API method from your application's Main
method/entry point:
SpAgent.Configuration.VerifyStoresInitialized();
This verifies that the initialization step outlined in License Store Initialization section has been performed. This must be done before any attempt is made to execute licensed code or to call the runtime API to query licenses.
Troubleshooting
The key requirement of this configuration is that your application and installer are run with sufficient privilege to
- create the base directory (e.g. C:\ProgramData)
- create folders within the base directory (e.g. MyCompany\MyProduct\MyVersion
- write files within the above area
Any failures will result in an Exception derived from StorageInaccessibleException
.
Installation time
Sp.Agent.Storage.WritingStorageInaccessibleException
- The store initialization needs to run in a privileged user context. Make sure that the process that runs store initialization has proper permissions.
Application runtime
Sp.Agent.Storage.WritingStorageInaccessibleException
- License Store isn't accessible for writing. Usually it means that the License Store Initialization step hasn't been performed.
Comments
0 comments
Article is closed for comments.