Class MirageLicenseProvider

Licensing implementation for the Mirage Licence Protector

Inheritance

System.Object

MirageLicenseProvider

Implements

ISerialLicenseProvider

IActivationKeysLicenseProvider

ILicenseProvider

System.IDisposable

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: Sartorius.SAF.Licensing.Mirage

Assembly: Sartorius.SAF.Licensing.Mirage.dll

Syntax

public sealed class MirageLicenseProvider : ISerialLicenseProvider, IActivationKeysLicenseProvider, ILicenseProvider, IDisposable

Remarks

To use the Mirage License Provider add the Sartorius.SAF.Licensing.Mirage nuget package to your project.

The license provider requires the following configuration entries:

ReadKey	This key is used for decryption of the license file. It is generated when the Mirage license is created. Provide the key as System.Security.SecureString. It is also possible to provide it as System.String but this is not recommended.

For convenience use the typed configuration object MirageLicenseConfiguration.

This license provider supports migration of licenses by using MirageMigration.

When the Serial is set the license will be configured upon application of an unlock key to be in the desired state after product activation.
When the serial was not set when an unlock key is applied and there are features which have any other value than 0 (no change) for the ActivationState after product activation' tag the serial will be set to '<Unknown>' to ensure the correct licensing workflow.
It is recommended to set a serial if your product has such a licensing requirement.

Contact the SAF support for creation of Mirage licensing projects.

When deploying you have to include LicProtector510.dll and (on 64-bit systems) Sartorius.SAF.Surrogate.exe.

Examples

The following example shows how to configure the Mirage license provider. You have to create a class that is derived from LicenseConfiguration.

    public class MyConfiguration : LicenseConfiguration
    {
        public MyConfiguration()
        {
            Add("ReadKey", LicensingTools.ReadKey);
        }
    }

You can also provide the configuration by using the typed configuration object MirageLicenseConfiguration.

    public class MyTypedConfiguration : MirageLicenseConfiguration
    {
        public override SecureString ReadKey => LicensingTools.ReadKey;
    }

The following example shows how to import the Mirage license provider. Do not import the implementation directly but import the ILicenseProvider interface.

        [ImportingConstructor]
    public LicensingExamples(ILicenseProvider licenseProvider)
    {
        this.licenseProvider = licenseProvider;
    }

The following example illustrates the complete licensing workflow. Use the ISerialLicenseProvider interface in this case.

                // The application is published with a default license file
                // on first start it is a demo version
                // if the demo was started before the demo could have expired now

                // The demo can expire anytime when the application runs. Subscribe to license changes to react to such an expiration.
                licenseProvider.LicenseChanged += OnLicenseChanged;

                // ask for the main feature
                var result = licenseProvider.Checkout("SIM001");
                if (result.State.HasFlag(FeatureState.Licensed))
                {
                    // The feature is available the functionality can be provided to the user
                    // If you are providing a demo or timed licenses, the license state could change during usage of the application
                }

                // for information purposes you could show information about the current license state to the user
                // or check the complete license status for any purpose of your application.
                var licenseInfo = licenseProvider.GetLicenseFileInfo();
                var mainFeatureInfo = licenseInfo.FeatureInfos["SIM001"];

                // When a customer registers and buys licenses deliver the hardware ids to order management
                var hardwareIds = licenseProvider.GetHardwareIds();

                // get some keys (e.g. via user interface, user enters the keys)
                var keys = GetKeys(hardwareIds);

                // if needed the keys can be validated before applying them
                var keyInfos = licenseProvider.GetActivationKeyInfos(keys).ToList();
                foreach (var info in keyInfos.OfType<ProtectionKeyInfo>())
                {
                    // Protection keys actually bond the license file to the hardware.
                    // they contain info about the hardware id and the type of hardware id
                    Trace.WriteLine($"Protection key for '{info.HardwareId}', type {info.ProtectionType}.");
                    Trace.WriteLine($"The key can be applied on this hardware: {info.IsApplicable}.");
                }

                foreach (var info in keyInfos.OfType<FeatureKeyInfo>())
                {
                    // Feature Keys provide licenses for additional features
                    Trace.WriteLine($"Activation key for '{info.FeatureId}' with {info.LicenseCount} licenses, valid for {info.Days}.");
                    Trace.WriteLine($"The key can be applied on hardware with id: {info.HardwareId}.");
                }

                foreach (var info in keyInfos.OfType<InvalidKeyInfo>())
                {
                    // invalid keys cannot be applied to the hardware or are formatted wrongly
                }

                // for correct Mirage workflow set the serial before applying an unlock key
                licenseProvider.Serial = currentSerial;

                // when applying keys the LicenseChanged event will also be raised.
                // So changed to the user interface when activating or deactivating new features can be done in one place.
                licenseProvider.ApplyActivationKeys(keyInfos.OfType<ProtectionKeyInfo>().Single().Key);

                // after applying the keys the keys the license info will reflect the new license state
                licenseInfo = licenseProvider.GetLicenseFileInfo();
                mainFeatureInfo = licenseInfo.FeatureInfos["SIM001"];

Properties

View Source

Serial

Gets or sets the serial.

Declaration

public string Serial { get; set; }

Property Value

Type	Description
System.String

Remarks

When the serial was not set when an unlock key is applied and there are features which have any other value than 0 (no change) for the ActivationState after product activation' tag the serial will be set to '<Unknown>'.

Methods

View Source

ApplyActivationKeys(String[])

Apply the given activation keys.

Declaration

public void ApplyActivationKeys(string[] activationKeys)

Parameters

Type	Name	Description
System.String[]	activationKeys

Exceptions

Type	Condition
System.ArgumentNullException	`keys` is `null`.
System.ArgumentException	`keys` is empty.
LicenseKeysException	One or more of the activation keys specified by `keys` could not be activated.
InvalidLicenseException	The license file is damaged or incomplete.
InvalidLicenseFileException	The license file is not a valid license file.
LicenseException	An unknown exception occurred. See the System.Exception.InnerException for details.
LicenseFileAccessException	The license file could not be accessed.
SystemDateChangedException	The system date was tampered with and the application is locked.

View Source

ApplyLicense(Stream)

Applies the license from the specified stream.

Declaration

public void ApplyLicense(Stream stream)

Parameters

Type	Name	Description
System.IO.Stream	stream	The stream of the license file.

Exceptions

Type	Condition
InvalidLicenseException	The license file is damaged or incomplete.
InvalidLicenseFileException	The license file is not a valid license file.
LicenseException	An unknown exception occurred. See the System.Exception.InnerException for details.
LicenseFileAccessException	The license file could not be accessed.

View Source

ApplyLicense(String)

Applies the license from the specified file path.

Declaration

public void ApplyLicense(string path)

Parameters

Type	Name	Description
System.String	path	The path to the new license file.

Exceptions

Type	Condition
System.IO.FileNotFoundException	The file specified by `path` could not be found.
InvalidLicenseException	The license file is damaged or incomplete.
InvalidLicenseFileException	The license file is not a valid license file.
LicenseException	An unknown exception occurred. See the System.Exception.InnerException for details.
LicenseFileAccessException	The license file could not be accessed.

View Source

Checkin(String)

Checks in the feature with the specified feature identifier.

Declaration

public void Checkin(string featureName)

Parameters

Type	Name	Description
System.String	featureName

Exceptions

Type	Condition
System.ArgumentNullException	`featureId` is `null`.
FeatureNotFoundException	The feature with the specified id does not exist.
InvalidLicenseException	The license file is damaged or incomplete.
InvalidLicenseFileException	The license file is not a valid license file.
LicenseException	An unknown exception occurred. See the System.Exception.InnerException for details.
LicenseFileAccessException	The license file could not be accessed.
SystemDateChangedException	The system date was tampered with and the application is locked.

View Source

Checkin(String, Int32)

Checks in the feature with the specified feature identifier and count.

Declaration

public void Checkin(string featureName, int count)

Parameters

Type	Name	Description
System.String	featureName
System.Int32	count	The count of licenses to check in for the specified feature.

Exceptions

Type	Condition
System.ArgumentException	The `count` parameter is less than `1`.
System.ArgumentNullException	`featureId` is `null`.
FeatureNotFoundException	The feature with the specified id does not exist.
InvalidLicenseException	The license file is damaged or incomplete.
InvalidLicenseFileException	The license file is not a valid license file.
LicenseException	An unknown exception occurred. See the System.Exception.InnerException for details.
LicenseFileAccessException	The license file could not be accessed.
SystemDateChangedException	The system date was tampered with and the application is locked.

View Source

Checkout(String)

Checks out the feature with the specified identifier.

Declaration

public CheckoutInfo Checkout(string featureId)

Parameters

Type	Name	Description
System.String	featureId	The identifier of the feature to check out.

Returns

Type	Description
CheckoutInfo	A CheckoutInfo containing info about the checkout process.

Exceptions

Type	Condition
System.ArgumentNullException	`featureId` is `null`.
FeatureNotFoundException	The feature with the specified id does not exist.
InvalidLicenseException	The license file is damaged or incomplete.
InvalidLicenseFileException	The license file is not a valid license file.
LicenseException	An unknown exception occurred. See the System.Exception.InnerException for details.
LicenseFileAccessException	The license file could not be accessed.
SystemDateChangedException	The system date was tampered with and the application is locked.

View Source

Checkout(String, Int32)

Checks out the feature with the specified identifier and the specified count.

Declaration

public CheckoutInfo Checkout(string featureId, int count)

Parameters

Type	Name	Description
System.String	featureId	The identifier of the feature to check out.
System.Int32	count	The count of licenses to check out for the specified feature.

Returns

Type	Description
CheckoutInfo	A CheckoutInfo containing info about the checkout process.

Exceptions

Type	Condition
System.ArgumentException	The `count` parameter is less than `1`.
System.ArgumentNullException	`featureId` is `null`.
FeatureNotFoundException	The feature with the specified id does not exist.
InvalidLicenseException	The license file is damaged or incomplete.
InvalidLicenseFileException	The license file is not a valid license file.
LicenseException	An unknown exception occurred. See the System.Exception.InnerException for details.
LicenseFileAccessException	The license file could not be accessed.
SystemDateChangedException	The system date was tampered with and the application is locked.

View Source

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration

public void Dispose()

View Source

GetActivationKeyInfos(String[])

Get information about the provided activation keys.

Declaration

public IEnumerable<KeyInfo> GetActivationKeyInfos(params string[] keys)

Parameters

Type	Name	Description
System.String[]	keys	The license keys that should be analyzed.

Returns

Type	Description
System.Collections.Generic.IEnumerable<KeyInfo>	A list of KeyInfos containing all information provided by the license `keys`.

Exceptions

Type	Condition
System.ArgumentNullException	`keys` is `null`.
System.ArgumentException	`keys` is empty.
InvalidActivationKeyException	One or more of the activation keys specified by `keys` is invalid or not valid for the current product.
InvalidLicenseException	The license file is damaged or incomplete.
InvalidLicenseFileException	The license file is not a valid license file.
LicenseException	An unknown exception occurred. See the System.Exception.InnerException for details.
LicenseFileAccessException	The license file could not be accessed.
SystemDateChangedException	The system date was tampered with and the application is locked.

View Source

GetFeatureInfo(String)

Gets the feature information for the specified feature.

Declaration

public FeatureInfo GetFeatureInfo(string featureId)

Parameters

Type	Name	Description
System.String	featureId	The identifier of the feature.

Returns

Type	Description
FeatureInfo	The information for the specified feature.

Exceptions

Type	Condition
System.ArgumentNullException	`featureId` is `null`.
FeatureNotFoundException	The feature with the specified id does not exist.
InvalidLicenseException	The license file is damaged or incomplete.
InvalidLicenseFileException	The license file is not a valid license file.
LicenseException	An unknown exception occurred. See the System.Exception.InnerException for details.
LicenseFileAccessException	The license file could not be accessed.
SystemDateChangedException	The system date was tampered with and the application is locked.

View Source

GetHardwareIds(Int32[])

Gets the hardware identifiers for the specified types.

Declaration

public IEnumerable<HardwareId> GetHardwareIds(params int[] ids)

Parameters

Type	Name	Description
System.Int32[]	ids	The identifiers of the HardwareIds to get. If this is empty all hardware ids will be returned.

Returns

Type	Description
System.Collections.Generic.IEnumerable<HardwareId>	All hardware ids or the hardware ids identified by `ids`.

Exceptions

Type	Condition
InvalidLicenseException	The license file is damaged or incomplete.
InvalidLicenseFileException	The license file is not a valid license file.
System.Collections.Generic.KeyNotFoundException	The one of the requested ids is out of the supported range.
LicenseException	An unknown exception occurred. See the System.Exception.InnerException for details.
LicenseFileAccessException	The license file could not be accessed.
SystemDateChangedException	The system date was tampered with and the application is locked.

View Source

GetLicenseFileInfo()

Gets information about the license file.

Declaration

public LicenseFileInfo GetLicenseFileInfo()

Returns

Type	Description
LicenseFileInfo	An instance of LicenseFileInfo that contains information about the license file.

Exceptions

Type	Condition
InvalidLicenseException	The license file is damaged or incomplete.
InvalidLicenseFileException	The license file is not a valid license file.
LicenseException	An unknown exception occurred. See the System.Exception.InnerException for details.
LicenseFileAccessException	The license file could not be accessed.
SystemDateChangedException	The system date was tampered with and the application is locked.

Events

View Source

LicenseChanged

Occurs when the license is changed due to the expiration of features or application of a new license or license keys.

Declaration

public event EventHandler<LicenseEventArgs> LicenseChanged

Event Type

Type	Description
System.EventHandler<LicenseEventArgs>

Remarks

The event can occur when timed licenses (e.g. demo or subscription licenses) expire. It will occur at the time the license expires or shortly after. For many license providers (e.g. Mirage LicProtector) this kind of expiration will occur at midnight.

The event can also occur when a license is changed by applying a license file (by using ApplyLicense(String) or ApplyLicense(Stream)) or when license keys are applied (by using ApplyActivationKeys(String[])). In these cases the event is directly while the methods triggering the license change are executed.

The events will always be raised on the thread that first did subscribe to the event.

Implementations of ILicenseProvider should always use weak event references to prevent routing event subscribers.

Implements

ISerialLicenseProvider

IActivationKeysLicenseProvider

ILicenseProvider

System.IDisposable

Extension Methods

CollectionExtensions.AddRange<T, TCollection>(TCollection, IEnumerable<T>)

SerializableObjectCloneExtension.Clone<T>(T)

Class MirageLicenseProvider

Inheritance

Implements

Inherited Members

Namespace: Sartorius.SAF.Licensing.Mirage

Assembly: Sartorius.SAF.Licensing.Mirage.dll

Syntax

Remarks

Examples

Properties

Serial

Declaration

Property Value

Remarks

Methods

ApplyActivationKeys(String[])

Declaration

Parameters

Exceptions

ApplyLicense(Stream)

Declaration

Parameters

Exceptions

ApplyLicense(String)

Declaration

Parameters

Exceptions

Checkin(String)

Declaration

Parameters

Exceptions

Checkin(String, Int32)

Declaration

Parameters

Exceptions

Checkout(String)

Declaration

Parameters

Returns

Exceptions

Checkout(String, Int32)

Declaration

Parameters

Returns

Exceptions

Dispose()

Declaration

GetActivationKeyInfos(String[])

Declaration

Parameters

Returns

Exceptions

GetFeatureInfo(String)

Declaration

Parameters

Returns

Exceptions

GetHardwareIds(Int32[])

Declaration

Parameters

Returns

Exceptions

GetLicenseFileInfo()

Declaration

Returns

Exceptions

Events

LicenseChanged

Declaration

Event Type

Remarks

See Also

Implements

Extension Methods

See Also