Troubleshooting SQL Comparison SDK licensing

Category: Licensing & activation
Date: 23 Oct 2009
Product: SQL Comparison SDK
Versions: SQL Comparison SDK 7,8 SQL Toolkit 5 & 6
Platforms: Microsoft Visual Studio 2003 and 2005

Often there are problems licensing SQL Comparison SDK applications, especially when upgrading versions. The following information outlines the common causes and solutions for problems that arise whilst applying a Red Gate serial number to a programming project that integrates the Red Gate SQL Comparison APIs.

Before you begin ensure you have a valid SQL Comparison SDK (SQL Toolkit) serial number. If you do not have a valid, activated serial number, the applications you distribute will display a trial expiry dialog box and will stop working after a period of time at the deployment site. It is possible for an SDK application to continue functioning on the computer used for application development if the licence has been activated previously, so it is important to test that the licensing has been applied correctly before deploying the application to your end-users.

1. To set up the licensing for an application that integrates the SDK's data comparison APIs
_________________________________________

Install SQL Data Compare (or Red Gate SQL Bundle containing SQL Data Compare) and note down the installation folder. This location, by default, will be:
C:\Program Files\Red Gate\SQL Data Compare <version>\, where <version> is the major version number of the product.
When adding a reference to the Red Gate components in your Visual Studio project, the assemblies that you choose will be found in this location. Visual Studio should also add this location to your references path automatically so the necessary Red Gate licensing components will function properly at build-time as well. With Vista, make sure you open Visual Studio with an admin account.

   a) Ensure you have a valid serial number (if you do not have a valid, activated serial number, the applications you distribute will display a trial expiry dialog box and will stop working when your trial expires).
   b) Add a licenses.licx file to your C# or Visual Basic .NET project in Visual Studio. If a licenses.licx file does not exist in your Visual Studio .NET project, you must create one by right-clicking the project, selecting 'Add', then 'New Item', then 'Text File' and call the file licenses.licx. Add the following entries in it on two lines (this is case sensitive):

RedGate.SQLCompare.Engine.Database,RedGate.SQLCompare.Engine
RedGate.SQLDataCompare.Engine.ComparisonSession,RedGate.SQLDataCompare.Engine

   c) Compile your application (click Build in Visual Studio or compile using the .NET compiler of your choice).
   d) If you have a valid licenses.licx file, you will be prompted for your serial number if this is the first time you've built a SQL Toolkit application.
       - In version 5 of the APIs, each time a new project is created, you are prompted for the serial number. In version 6 and up, the licence is available for all future SDK projects once activated.
       - When your application is built correctly, the end-user can run it without having to licence it again. Otherwise, the end-user will be presented with a dialog informing them that the SQL Comparison SDK is not licensed.
   e) Distribute your application to your end-user. You must distribute the files

      RedGate.SQL.Shared.dll
      RedGate.SQLCompare.Engine.dll
      RedGate.SQLCompare.Rewriter.dll
      RedGate.SQLCompare.ASTParser.dll
      and RedGate.SQLDataCompare.Engine.dll with your application.

      If the "compare to backup" functionality from SQL Data Compare 6 API is used, also include

      RedGate.BackupReader.dll
      RedGate.SQLCompare.BackupReader.dll

You do not need to distribute RedGate.Licensing.Client.dll as it is only used by Visual Studio during compile time. The licence is embedded in the assembly by the compiler.

2. To set up the licensing for an application that integrates the SDK's schema comparison APIs
_____________________________________

For SQL Compare API a similar approach exists namely:

Again all references should be pointing to the same directory:
C:\Program Files\Red Gate\SQL Compare <version>\.

   a) If you do not have a valid, activated serial number, the applications you distribute will display a trial expiry dialog box and will stop working after 14 days.
   b) Add a licenses.licx file to your C# or Visual Basic .NET project in Visual Studio. If a licenses.licx file does not exist in your Visual Studio .NET project, you must create one by right-clicking the project, selecting 'Add', then 'New Item', then 'Text File' and call the file licenses.licx. Add the following entry line (this is case sensitive):

RedGate.SQLCompare.Engine.Database,RedGate.SQLCompare.Engine

   c) Compile your application.
   d) If you have a valid serial number and a valid licenses.licx file, your executable file will run without displaying the trial expiry dialog box.
   e) Distribute your application. You must distribute the files
      RedGate.SQL.Shared.dll,
      RedGate.SQLCompare.Engine.dll,
      RedGate.SQLCompare.Rewriter.dll,
      RedGate.SQLCompare.ASTParser.dll

You do not need to distribute RedGate.Licensing.Client.dll as it is only used by Visual Studio during compile time. The licence is embedded in the assembly by the compiler.

3. Licenses.licx Help
__________________

There are a few guidelines for the licenses.licx file that may help:

Don't copy the licenses.licx file from another folder manually, for instance using a command prompt or Windows Explorer. It should be added as a new item at the Visual Studio project level with a build action of "Embedded Resource". Visual Studio 2003 sometimes ignores changes to embedded resources, so at times it may be advisable to simply recreate the file if changes that you make are not being enforced. If possible, use Explorer and delete licenses.licx, then go back into the project, right-click, add new, file, call it licenses.licx.

Check the properties of licenses.licx and make ABSOLUTELY SURE the build action says 'Embedded Resource'.

The entries in licenses.licx are case-sensitive, so for SQL Data Compare, so check the entries carefully

If you go to build the project, and get an error along the lines of 'unable to resolve type...' , licenses.licx has been picked up by Visual Studio, but the format is wrong.

If a licence file produced as the result of a successful activation is present on the build computer, the build will silently succeed. To double-check that your assembly has been licensed successfully,
you may use a tool such as .NET Reflector (http://reflector.red-gate.com/download.aspx), open your assembly, expand 'resources', locate a resource called <YourAssemblyFileName>.licenses, view the resource, and make sure that the resource contains 'RedGate.SQLCompare.Engine.Database' and also 'RedGate.SQLDataCompare.Engine.ComparisonSession' if you had also referenced the Data Compare Engine in your project.

Sql Comparison SDK versions 6 and up will retain the product license in a global location, so it should be necessary to activate the product only once. Subsequent builds will succeed silently without having to re-enter the product serial number. Versions lower than 6 would retain the activated licence in an application-specific location, so the SDK would need to be re-activated every time a new SDK project was created.

This is useful to know because it makes a shortcut possible where the SQL Toolkit serial number does not need to be continually entered for every new project. Once an SDK project is activated on the build machine, a licence file (SQL Toolkit_v5.lic) is saved to your hard disk. Moving this file into the references path for any new project on the same machine should suppress the serial number requester and directly enter the licensing details from the licence file instead.

You do not need to distribute RedGate.Licensing.Client.dll as it is only used by Visual Studio during compile time. The licence is embedded in the assembly by the compiler and there is no further need for this file if the SDK had been licensed successfully. If the application being deployed shows an error message relating to a binding failure to this assembly, then this indicates that the licensing for your assembly had not been successful and it needs to be rebuilt and properly licensed.

4. Licencing - To Sum Up
_____________________

   a) Create your new project
   b) Add licensed object assembly references (RedGate.SQLCompare.Engine.dll, etc) to the licx file
   c) Save and compile
   d) An activation dialog should pop up
   e) Click the activate button on that message box
   f) Enter your valid serial number in the edit box provided
   g) Choose email or internet and continue
   h) Upon success - a .lic file has now been generated on this machine - nag screen is gone, continue coding.

5. Removing the serial number that has already been activated
___________________________________________________

If the registry key below is removed then you can reactivate the product with a different serial number:

HKEY_LOCAL_MACHINE\SOFTWARE\Red Gate\Licensing\<product>\<version>\SerialNumber

(Product will either be SQL Comparison SDK or SQL Toolkit)

6. Web and SQL ToolKit
____________________

If the SDK component has been included as part of an ASP .NET web application, webservice, or website, then there is a problem with licensing because the dialog requesting the serial number cannot be displayed, resulting in an error: "It is invalid to show a modal dialog "

The recommended workaround for licensed customers is to move all SQL Comparison API functions into a stand-alone class library project, then reference that dll from your web application. Because the licence will be embedded into the dll assembly, the web application will not error because the ASP .NET dynamic compilation fails because it cannot display the activation requester. Unfortunately, there is no workaround for unlicensed customers as the "nag requester" cannot be displayed, making it impossible to evaluate SQL Comparison SDK on an ASP .NET web application. A permanent serial number is required to use SQL Comparison SDK with a web application.