Quick Start Guide (TA6)

THIS DOCUMENT APPLIES ONLY TO THE LEGACY MICROSOFT.LICENSING RUNTIME - FOR THE SPAGENT RUNTIME PLEASE REFER TO THE ONLINE SPAGENT DOCUMENTATION

This Quick Start Users Guide will get you up and running with the Software Potential service using the Microsoft.Licensing runtime. 

Before you start!

The starting point for this document assumes that you have already:

1.        A valid Software Potential subscription
2.        Received your trial account key
3.        Used the key to create your account on the portal.
If you haven’t done this, then register for your free 30 day trial here.
 

Step 1: Setup Your Software Potential Environment

Setting up your Development Environment is very straight forward; however it is best completed by a software developer.
1.     Create your Permutation
To get started, you need to generate a unique private permutation for your product. A permutation file contains a unique one way transformation which, when loaded into Code Protector, transforms the CIL of your assembly to be protected so that the protected assembly cannot be reversed engineered.

1.     Logon to the Software Potential portal at https://srv.softwarepotential.com

2.     Click Accounts -> Manage Permutations -> Create Permutation

3.     Enter a name for your permutation and click OK

4.     Eventually (click refresh) the status field will change from Creation Pending to Done. Your Permutation has been created.

 

2.  Download Code Protector and Permutation
To be installed the permutation and the code protector tool need to be saved locally to your machine. Save them where they are easy to find later.
1.     If not already logged on, logon to the Software Potential portal at https://srv.softwarepotential.com
2.     Click on Accounts -> Manage Permutations and select your permutation by clicking on the corresponding record in the table of permutations.
3.     Download the Code Protector .msi file and Permutation file using the links in the Downloads column and save them locally.
 
3.  Install Code Protector and Permutation
On your development machine locate the Code Protector file downloaded  in the last step and double click the .msi to initiate the install. Once installed:
1.      Launch Code Protector
2.      When prompted by the Code Protector logon to the Software Potential service using the  same credentials used in the previous steps
3.      Select Install Permutation
4.      Browse to the location of the previously saved Permutation file and click OK
On completion of this step your permutation should be listed in Code Protector.
 
3.  Reference the Permutation Runtime Files
The downloaded Permutation file contains the Runtime components/assemblies, required for the execution of your application code when protected. You need to ensure these assemblies are referenced in your Visual Studio project by adding the following entries in your csproject or vbproj file as appropriate:
  <PropertyGroup>
    <SlpsRuntimeVariant><Variant></SlpsRuntimeVariant>
    <SlpsRuntimePermutationId><Permutation ID></SlpsRuntimePermutationId>
  </PropertyGroup>
  <Import Project="C:\Program Files (x86)\InishTech SLP Code Protector\Slps.Runtime.References.targets" />

where

<Variant> is the set of runtime assemblies required for your particular application and licensing model; must be selected from the following:

  • Standard: Used for Desktop
  • Distributor: Floating/concurrent Licensing
  • SaaS SDK: USed with SaaS applications on Azure
  • Sp.Agent: Used for Web or Dynamics CRM applications

<Permutation ID> is the name of the permutation file that you downloaded in Step 2 above.

Now your Software Potential  Development Environment is set up. The next step is to create products, features and SKUs in the Software Potential portal.

 

Step 2: Manage products and SKU’s

Once you have your InishTech Development Environment set up, you can start managing products and editions (SKU’s) in the portal. NOTE: The developer can continue with this step, but equally a product manager / commercial manager can take over. 
 
1.  Creating Products
This is the process of creating and managing products, versions and editions of your software for the purpose of licensing. The first task is to define and describe your products to the licensing system.
1.     Logon to the Software Potential portal at https://srv.softwarepotential.com
2.     Click Manage Products -> Add/Edit a Product and describe the product in the system in terms of Name, Version Number and Description, then click OK.
 
2.  Defining Features
When you create a product or a version, you define the licensable features of the product. (You can have as few as zero features in your product - in this case the product is licensed as a whole).
1.     If you have not already done so logon to the Software Potential portal at https://srv.softwarepotential.com
2.     Click Manage Products and then highlight the Product-Version from the list of names provided.
3.     Click Edit and enter a feature name and description. Click + and repeat as required until all req’d features have been defined.
 
3.  Creating SKUs
SKUs are specific editions of your software – i.e. packages created for the purpose of sale and distribution. SKUs have features, entitlements and limitations associated with them e.g. Trial, Standard, Professional and Enterprise Editions. To create a SKU:
1.     If you have not already done so logon to the Software Potential portal at https://srv.softwarepotential.com
2.     Click on Manage SKU which will automatically default to Create a new SKU page
3.     Define your SKU according to your business requirements.
4.     A SKU serves as a template from which one can subsequently generate licenses. For more information on the parameters you can set for a SKU, consult the Getting Started Guide.
You have now created products, features and SKUs in the InishTech portal. The next step is to protect and license your software.
 

Step 3: Add code protection and licencsing

Code Protection is an integral part of the service and the first step in the licensing process. It allows you to protect your application against misuse and the threat of piracy and reverse engineering.
For an efficient and error free code protection process we recommend that it be automated and integrated with your build environment. This will ensure the code protection step occurs automatically during the build process when the appropriate compilation symbol (SLPS_PROTECT) is set for the active build configuration.
For the purpose of a trial, use the demo app InishTech SLP Services Tutorial for C# (or Native C++) .
 
1.  Protecting your Code
To enable automation of the code protection step within your build environment, you first need to store the Code Protector settings in a SLMCfg configuration file that will be used by Code Protector when protecting your code
2.      Select Project tab and in the right hand settings panel use the following default settings:
2.     Select Project tab and in the right hand settings panel use the following default settings:
         Permutation: <Previously Installed Permutation>
         Target Runtime Variant: Standard
         Product Name: <ProductName>
         OutPut Directory:  you can set your own directory if default is not appropriate.
3.     Select Add Modules to add one or more application assemblies to be protected
4.     On the Code Protector menu bar select File -> Save As and save the Code Protector configuration as <ProjectName>.SLMCfg file alongside your project file in your project directory (where ProjectName is the name of the project containing code to be protected and/or licensed.
5.     Add the conditional compilation (i.e., #define) symbol SLPS_PROTECT - referred to as DefineConstant within MSBuild properties - for the active build configuration. When this is set, the assemblies created by the build process will be both protected and licensed automatically using the settings in the SLMCfg file created earlier.
(NB For SLPS_PROTECT to be detected correctly all symbols must be delimited by semi-colons - the Visual Studio project system also accepts spaces and commas)
Your project is now set up to trigger code protection automatically, with Code Protector using the settings in the SLMCfg file.
 
2.  Selecting Methods for Protection and Licensing
In your application source code, mark each method to be protected and licensed with the protection attribute [Feature (“<Feature Name>”)] where Feature Name is the name (as defined in the Software Potential portal) of the Feature to be associated with the selected method.
See Support KB13 for further details on how to declaratively select methods for protection and/or licensing
At this point you can now build your application and the assemblies will be both protected and licensed
 
3.  Add a Custom Action to install the runtime components
To run a licensed application an appropriate license store must be created and configured on the target machine during application installation.
As per Support KB7 add a Custom Installer class and wire it up to a Custom Action triggered from your installer so that when end customer installs your application, the runtime license store will be installed as well.
 

Step 4: Build the application

Now build your application. On successful protection the assemblies in the relevant project output directory (e.g. bin/Release, bin/Debug as appropriate) are now protected with the required license checks implemented.
Your application is now protected and licensed and is ready for distribution to, and installation by, your customers. The next step is to create and issue licenses for the customer to activate your software.
 

Step 5: Software licensing

Once your customer has installed your protected application, a license will be required to run the licensed code within it. So you now need to create licenses and issue the associted Activation Keys to your customers.
The Software Potential service allows you to generate, activate and manage licenses to your software in the marketplace – both from pre-defined SKUs and ad hoc license generation “on demand”.
1.  Creating Licenses (from a SKU)
1.     Logon to the Software Potential service portal at https://srv.softwarepotential.com
2.     Click on Manage SKU à Create License from a SKU and then click Create License for the corresponding SKU
3.     Click Next to confirm your selection and then enter the Number of Licenses, Description, Customer Name (or select the customer from the list) and click Create Licenses.
 
2.  Creating Licenses (Ad Hoc Licenses)
1.     If you have not already done so logon to the Software Potential service portal at https://srv.softwarepotential.com
2.     Click on Manage Licenses and then within this page you can define the license parameters as required.
3.    Click Issue License.
You should now have an Activation Key that can be used to activate an installed instance of your protected application.
 
3.  Activating Licenses
License generation and activation are separate processes. If you attempt to run the protected application / protected methods, the Activation Wizard will pop up. There are 2 activation options:
1.      Online Activation – Where the license is activated automatically (over the web) by connecting to the InishTech portal.
2.      Manual Activation – Where a person activates the license manually by providing the license key direct to the application.
All your customer need do is enter their Activation Key and follow the instructions of the Activation Wizard.
 

Step 6: Moving on

To help you to move from a trial to a live environment, here are some more advanced scenarios and tips to get your app ready.
Advanced Licensing Scenarios
1.        Time limited licenses: time limited licenses are particular helpful for “Try before you Buy” situations. Set as a Non-Commercial license and set “Expiration Days” to a number (e.g. 30) and the licenses will expire after that time period.
2.        Upgrades: When the customer then decides to upgrade, you can either:
            i.         Issue commercial licenses to overwrite non-commercial ones automatically
           ii.         Re-issue the trial license but make it a commercial license that’s not time limited. The customer doesn’t need an extra license key but instead can re-activate the old one.
3.        Renewable licenses: If your customer pays on a subscription basis and you want auto-renewing licenses that simply check if they qualify for renewal. Licenses can be disabled at any time.  
 

Top Tips for a Production Environment

There are some additional steps one should take when using Software Potential in a production, rather than evaluation environment:
1.      Integrate code protection into the Visual Studio build process – Follow Support KB12. as recommended in the steps above so that licensing is applied automatically during build.
2.      Code protection declarative attributes – If you have not already done so combine with guidance in Support KB13 so there is no need to tick methods for protection/licensing in Code Protector UI.
3.      Install Runtime Components – If you haven't already done so include the installation of the SP Runtime components in your application installer as per Support KB7, so that when the end customer installs your app the SP runtime license store will be installed as welll.
4.      Activation Dialog customization – The activation dialog can be localized and you can create a custom Activation Wizard.
5.      Runtime and Web Service APIs – With the Runtime API you can access the core runtime licensing functionality directly from your application code; with the Web APIs one can introduce InishTech functionality into other IT systems.