Welcome to the SoftwarePotential.Configuration.Local.MultiUser-<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. This means 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. (See the SingleUser equivalent if your application is intended to be used by a single user on each machine.)
License Storage Location Base Path
Adding this NuGet package to your application configures licenses to be stored in a shared Application Data folder on Windows i.e. out of the box, the directory used by the code in this package results in a base path such as
On Linux the default base directory is /usr/share/, while on MacOS the default is /Library/Application Support/.
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.ConfigureStorageRelativePath() methods respectively (in
See Customization of SpAgent Storage Configuration for more details on customization of the SpAgent.MultiUserStorageCustomization file.
License Store Initialization
The shared licensed store needs to be created and initialized by a privileged user (local administrator) during application deployment/installation.
On Windows, 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.
- When the commandline option is supplied, have your
- exit to allow the rest of the installation to complete (i.e. the application should exit immediately)
- Have your installer / installation script call your application with the installation option:
1.3. Using a custom action in a Windows Installer
It is also possible to use custom action in a Windows Installer to initialize a license store. Please see the relevant installer product documentation for details on how to create a customer action .
On Linux or MacOS, the shared store must be explicitly created and initialized by a privileged user (local administrator) by calling
SpAgent.Configuration.StoresInitialization.Initialize() as part of the application installation process.
License Store Verification
We recommend calling the following API method from your application's
Main method/entry point:
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.
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
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.
Sp.Agent.Storage.WritingStorageInaccessibleException- License Store isn't accessible for writing. Usually it means that the License Store Initialization step hasn't been performed.