Helpful Tech How-To Tips

Do you need to add your serial number validation routines to your MSI package? Here you'll find useful background information and step-by-step instructions on how to do so.

BACKGROUND

In a Visual Studio Installer (VSI) project, developers have the ability to add a Customer Information dialog box in the user interface, which by default has an input field for a serial number. However, Visual Studio Installer provides minimal support for validating this field. Developers can add their own serial number validation routines using a Microsoft Windows Installer SDK tool called Orca.

INSTALLING AND RUNNING ORCA
You will need the Orca tool to follow the instructions in this blog. To install and run Orca, do the following -

Download the Windows Installer SDK, tools, and documentation from -
http://www.microsoft.com/downloads/details.aspx?FamilyId=A55B6B43-E24F-4EA3-A93E-40C0EC4F68E5&displaylang=en

Install the Orca editor by double-clicking the Orca.msi file in the \Microsoft SDK\bin folder.

Click Start, point to Programs, and then click Orca.

On the File menu, click Open, and then browse to the .msi file that you want to edit.

STEP-BY-STEP INSTRUCTIONS

I – Set up your VSI project

Create an empty installer project with VSI.

Add a Customer Information dialog box to the user interface. Do not change the default properties for the dialog box.

Build the project.

II – Create a custom action DLL

Create a custom action DLL that contains you serial number validation logic

Wrap your validation code into a fucntion the following function prototype - UINT __stdcall VerifyPID(MSIHANDLE hInstall)

SAMPLE CODE -

UINT __stdcall VerifyPID(MSIHANDLE hInstall)
{
   // Local variables
   UINT    nRetVal = 0;
   UINT    uiMsiRc;
   TCHAR   szPidKey[MAX_PATH];
   DWORD   dwBuffer;

   dwBuffer = sizeof(szPidKey)/sizeof(TCHAR);

   // First Step - Get the PIDKEY property
   uiMsiRc = MsiGetProperty(hInstall, TEXT("PIDKEY"), szPidKey, &dwBuffer);

   if (ERROR_SUCCESS != uiMsiRc)
   {
      MessageBox(NULL, "PIDKEY", "Not able to retrieve PIDKEY property", MB_OK  MB_ICONEXCLAMATION);
      return 0;
   }

   //Insert code to check PIDKEY here
   int str = lstrcmp(szPidKey, "123 -4567890");

   //If PIDKEY passes check
   if (str == 0)
      MsiSetProperty(hInstall, "PIDCHECK", "TRUE");
   //If PIDKEY doesn't pass check
   else
   {
      MsiSetProperty(hInstall, "PIDCHECK", "FALSE");
      wsprintf(szText, "Please enter the correct code");
      MessageBox(NULL, szText, "PIDCHECK", MB_OK  MB_ICONINFORMATION);
   }

   return 0;
}

Note that the PIDKEY property has the value of "XXX -XXXXXXX" where X is a number and there is both a space and hyphen.

On the Tools menu, click the Options Directories tab in your DLL project, and then add the path to the Windows Installer SDK's Include and Lib directories.

In the Project Settings dialog box, add msi.lib to the library list.

Then, either use a .DEF file or the __declspec(dllimport) attribute to export the DLL functions.

III – Link your Validator to your Windows Installer Package using Orca

Open the Microsoft Windows installer package (.msi) file that you built with VSI in Orca.

Add the DLL to the Binary table and name it VerifyPIDDll.

Add a new custom action to the Custom Action Table:
In the ControlEvent table, find the UserNameForm, which corresponds to the Customer Information dialog box from VSI.

Make all changes to the existing rows with UserNameForm in the Dialog column and Next in the Control column:
- Replace the ValidateProductID Event with DoAction. On the same row, replace the Argument {} with MyPIDChecker.
- Make sure that the value for the Condition column in the row with the EndDialog event is: UserNameForm_NextArgs="" AND UserNameForm_ShowSerial=""
- Using the PIDCHECK property which was set your custom validation code, make sure that the value for the Condition column in the row with the NewDialog event is:
  (PIDCHECK="TRUE") AND UserNameForm_NextArgs<>"" AND UserNameForm_ShowSerial<>""
- Make sure that the value for the Condition column in the row with the [UserNameForm_ShowSerialDisabled] event is: PIDCHECK="TRUE"
Save the .msi file.

Your validator code should now be successfully integrated with your MSI file.

You can verify a successful integration by running the MSI and verifying that it indeed prompts for and validates a serial number during installation.

A REQUEST: If you found this helpful, please consider adding a link to this post from your blog, so others folks out there can also find and use this information. The link is http://helpful-tech-how-to-tips.blogspot.com/

Thanks guys!

How to Validate a Serial Number During Installation of your Windows Installer (MSI) Using Orca