Creating a simple MSI package

This tutorial will guide you step by step through the creation of a simple Advanced Installer project from scratch and building it in order to obtain a MSI package. It is addressed to those who have no previous experience in using the Advanced Installer application. et!s suppose that you want to create a package to install a simple text file" a story you wrote. #hoose an already existing text file on your local disk or create one by using the $%ew & Text 'ocument( right)click context menu in *indows +xplorer. %ame the file story.txt. ,pen it in your favorite text editor and type a couple of lines to give it some content. -. #reate project .. Add files /. 0uild and install 1. 2emove installed file 3. +dit product and company names 4. #reate shortcuts 5. #hange product version

1. Create project
If Advanced Installer is not currently running" start it by double)clicking on the desktop icon or by selecting it from the $Start & All 6rograms & Advanced Installer( menu. *hen the application starts" you will be presented a dialog where you can choose the

type of the project you want to create. Select the $Simple( type. 7ncheck the $7se wi8ard...( option. 6ress the 9 #reate 6roject : button. The new project has been created and from now on you will edit it.

Save the project by using the 9 Save : toolbar button and choose the file name and the destination folder. This will also be the folder where your MSI package will be created. ;ive it an appropriate name" story.aip for this example. A common mistake made by developers new to Advanced Installer is creating a project then copying it and using the copy as a base for a new project. This is wrong" it leads to duplicate 6roduct#ode and 7pgrade#ode. The article on 6roduct Identification explains why this is wrong in the <#opying your project files< section.

2. Add files
The most important step in creating a MSI package is adding a file or folder. Switch to the $=iles and =olders( page by selecting it in the left)side panel. The folders which interest you most are $Application =older( and $Application Shortcut =older(. In Application =older you can add the files and folders used by your application" this folder representing the installation folder. In Application Shortcut =older you can add shortcuts to your application" to a help file or to an 72 " this folder representing a folder in the $Start & All 6rograms( menu of the *indows taskbar. >ou can read more about these folders in the Install 6arameters page. #lick on the 9 Add =iles... : toolbar button" browse to your project!s folder and select

the story.txt file.

3. Build and install

%ow that you have added a file to your project let!s build the MSI package. #lick on the 9 0uild : toolbar button and a $0uild 6roject( dialog will appear showing you the build evolution. ,nce the build is complete" click on the 9 2un : toolbar button. A setup wi8ard will appear that will guide you through the install process of the $story.txt( file. #ongratulations? >ou have created your first Advanced Installer MSI package. 0y default" the story.txt file will be installed in #@A6rogram =ilesA>our #ompanyA>our Application. 0rowse to that folder in *indows +xplorer to check.

4. Remo e installed file

>ou can remove the installed file either from the $AddB2emove 6rograms( pane in the #ontrol 6anel or you can have it removed from within the Advanced Installer application itself. Simply press the 9 2un : button again without modifying anything and

the Setup wi8ard will appear. Select 9 2emove : in the second screen and wait until the uninstall process is complete. If you change anything in the project" pressing 9 2un : will cause a different package to be generated. The only way to uninstall the old one will then be from the $AddB2emove 6rograms( pane in #ontrol 6anel.

!. "dit product and compan# names

,f course" $>our #ompany( and $>our Application( aren!t too expressive names for the story you are trying to distribute. et!s change them. Switch to the $6roduct 'etails( page by selecting it in the left)side panel and edit

them to better values.

0uild and 2un the package again to check the results. 'on!t forget to uninstall afterwards.

$. Create s%ortcuts
Installing in the 6rograms =iles location is not of much use if we don!t create shortcuts to the installed file. *e will create two@ one in the $Start( menu and another one on the computer desktop. Start by switching back to the $=iles and =olders( page. Select the story.txt file by clicking on it" then click on the 9 %ew Shortcut : toolbar button. The $%ew Shortcut( dialog will appear" allowing you to customi8e the new shortcut.

#hange the shortcut name to $ ong Story( and click 9 ,C :. The new shortcut will be added in the Application Shortcut =older. That means that this shortcut will be installed in the $Start & All 6rograms & 6roduct %ame( menu of the Target #omputer. To also create a shortcut that will be installed on the Target #omputer!s desktop" select the 'esktop folder in the $=olders( tree and click the 9 %ew Shortcut : button. A file picker dialog will pop up" allowing you to select the target file of this new

shortcut. Select story.txt and press 9 ,C :. 6ress 9 ,C : again in the $%ew Shortcut( dialog" after you!ve changed the shortcut name to $ ong Story(. The new shortcut will be added to the $'esktop( folder. 0uild and 2un again to check the results" uninstall when you!re done.

&. C%ange product ersion

In time" you may want to release a new version of the story. Maybe you want to fix some issues discovered in the first release. %othing easier with Advanced Installer.

=irst" open the story.txt file your favorite text editor and add a couple of lines to it" so that we have an actual file change. Then switch to the $6roduct 'etails( page by selecting it in the left)side panel. +dit the

$6roduct Dersion( field to $..E.E(. *hen building" saving or selecting another page" you will be asked to generate a new 6roduct #ode. Answer $>es( if you want the new package to automatically upgrade the previous version of the story" if found on the target computer. If you answer $%o(" the two versions will be prevented from being installed simultaneously on the same computer.

'%e "nd
This concludes our tutorial. To learn more" please read the 6rofessional Installation tutorial.

Creating a (rofessional (ackage

This tutorial will guide you step by step into the creation and customi8ation of a Advanced Installer 6rofessional project. It is addressed to those who have completed the Simple Installation tutorial. et!s suppose you want to create a package for a text editor you have created. *e will use for this role Microsoft!s %otepad. This editor has some characteristics@ =or the editor to function properly some registry keys must be present on the target system. Suppose this editor is developed using Disual 0asic. In order to work" it needs Disual 0asic 4 2untime to be installed on the target machine. It has a type of file that it associated to" called" say" +'I file. -. #reate project .. +nter product details /. Set install parameters 1. Add files and folders to your project 3. Add registry keys and values to your package 4. Set launch conditions 5. Add 6rereFuisites G. #reate new file extensions and make file associations H. 0uild and Install -E. ,rgani8e your application into features --. Set dialogs to guide the user during install -.. Set package name and some more media options -/. Add environment variables to your project -1. Add custom actions to your installation package -3. Install and control services -4. Add merge modules to your project

-5. Set the 7I appearance of your installation package

1. Create project
If Advanced Installer is not currently running" launch it by double)clicking a desktop icon or selecting it from the $Start( menu. *hen the application starts" you will see a

dialog where you can choose the type of the project you want to create. Select 6rofessional and press the #reate 6roject button. The new project has been created and from now on you will edit it. Save the project and give it an appropriate name ) let!s say <Tutorial< for this example. +nglish is the default project language" but you can change it to any of the languages known by Advanced Installer.

2. "nter product details

%ow you can see the main view split in two panes. In the left pane" you can see all the options you have to edit in your current project" grouped in four categories. #lick on $6roject 'etails( option from the $6roduct Information( group to set the information seen by the user for your installation package. =ill the fields in the right pane with the corresponding data. Iere is an example of how this can be done@

=or further information about this page please see 6roduct 'etails Tab.

3. Set install parameters

>ou now have the general information on the 6roduct 'etails page filled in. ;o to the Install 6arameters page Jclick the Install 6arameters optionK. Set the default installation paths for the <Application =older< and <Application Shortcut =older< by using the combo boxes or the 9 +dit... : button. >ou can edit these fields" but the values from the combo boxes are the most common ones.

=or more information about these paths please see the Install 6arameters page.

4. Add files and folders to #our project

The next step is to add to the project the files andBor folders that compose your application. >ou will need an +'I file to test the editor!s file associations. Since it is a custom type of file" you will have to create it. 7se any text editor to create a <foo.txt<. Then rename it <foo.edi<. Select $=iles and =olders( from the $2esources( menu on the left pane.

#lick on the 9 Add =iles : toolbar button and select the files of your application. =or this example choose %otepad.exe from your *indows directory. 2epeat this step to include the =oo.edi file you have created. >ou can add in this way as many files as you

want. ,nce the files are added" their name will appear in a list in the right)side pane of the view. %ow let!s make a shortcut to the %otepad.exe file you just added. 2ight click on this file and choose $%ew Shortcut To )& Installed =ile(. In the newly appeared dialog choose a name for your shortcut and a location ) like in the following screen)shot. 6ress the ,C button and the shortcut will appear listed in the application shortcut folder.

=or more information please see the =iles and =olders page.

!. Add registr# ke#s and alues to #our package

et!s suppose that your application needs two registry entries. These are located in the <SoftwareA9Manufacturer:A96roduct%ame:ASettings< key. ,ne registry value is named <App6ath< and stores the path where your application is installed. The other one is named <AppSettings< and contains a value that shows the current settings of the application. ,n install it has the value </4<. Select the $2egistry( page. In the tree" select the <SoftwareA9Manufacturer:A96roduct%ame:< key. #lick on the 9 %ew Cey : toolbar button to create a key. +dit the key name to <Settings<. Add a value for it using the 9 %ew Dalue : toolbar button. In the <%ame< text field enter the name of your first key@ <App6ath<. 7se the 9 =older... : button and select <Application =older<. Since <'ata< is a =ormatted Type text field the value that it contains will be expanded at install time into the full path to your application!s location. 7se the same steps to create the <AppSettings< value. This time when creating the new key select <0inary< and type in the <'ata< field the number </4<.

,nce the registry keys and values are added" you can see them in the right)side pane of the view.

=or more information please see the 2egistry page.

$. Set launc%

conditions
;o to the < aunch #onditions< tab of the < aunch #onditions< page. If you wish that your application should be installed only on *indows %T 1.E or higher and not on *indows HxBM+" then you should do the following@ uncheck the <*indows HL from< check box check the <*indows %T =rom< check box

select <*indows %T 1.E< from the associated combo box

>ou can also create a custom launch condition which will make sure that the package will not be installed if the file <example.txt< does not exist on the partition on which *indows is installed. =or this you can follow these steps@ create a =ile search in the Search page set the file name to example.txt rename the search to =I + use the context menu to add a folder as the location of the search set this folder to 9*indowsDolume: Jthis is resolved to the partition on which *indows was installedK use the <Test Search< button on the toolbar to test the search go to the #ustom aunch #onditions tab in the < aunch #onditions< page use the 9 %ew... : button to add this launch condition@ #ondition@ =I + 'escription@ This application cannot be installed because the file <#@Aexample.txt< does not exist.

&. Add (rere)uisites

et!s suppose that your application reFuires the <My Application.exe< installation package to be installed. This package will install an application and it will create the registry entry IC+>M ,#A MMA#II%+ASoftwareAMy ApplicationADersion with the value -.E. If this application is not already present on the target machine" your package

will have to install it before deploying your application. =or this you can use the <6rereFuisite< feature. ;o to the <6rereFuisites< page. >ou can add any software that you need. Advanced Installer also comes with a list of common used prereFuisites" for which all the settings are already defined. After creating them" you only have to specify the source for the setup file. Select <%ew 6ackage 6rereFuisite< from the context menu. If you have the <My Application.exe< installation package on your computer you can use the <7se files from disk< option and select it when prompted. >ou can also set the location of the prereFuisite as an 72 from where the file can be downloaded.

After the properties of the prereFuisite have been set you need to set the detection criteria by using the Install #onditions tab.

Since the

prereFuisite application" let!s say" creates a registry entry" we can use it as a detection criteria in the Searches section.

=or more information please see the 6rereFuisites page.

*. Create ne+ file e,tensions and make file associations

>our application uses files with a particular extension Jin our example that is <edi<K. >ou may want to associate that type of files to be opened or edited with your application. Advanced Installer helps you do this in a very simple way. #hoose $=ile Association( from the $2esources( options group. 7se the 9 %ew +xtension : toolbar button to create a new extension@ <edi<. +nter a description of this extension in the appropriate field in the right)side pane. >ou may choose an icon to be displayed for all the files with the extension you created.

=or every extension contained in your application" you need to add at least one verb. The name of the verb will be seen in the context menu that appears when you right click on a file of <edi< type in *indows +xplorer. =or this example" you should leave the defaults settings. The effect is that when you double click a file or you choose the <,pen< action from a context menu of an <edi< file" the application is automatically launched with the command line argument specifying the absolute path of the chosen

file. >ou can add as many verbs as you want for an extension. =or more information please see the =ile Associations page.

-. Build and Install

>ou are now ready to test your program. 0uild and install your program as described in the Simple Installation tutorial.

>ou can test if the file associations are working properly. ook in the folder where you have installed the program and double)click the +'I file. This should open using the %otepad.exe file that you have installed. Also you can verify the value written in the registry Jusing 2egedit.exeK. >ou will see the value of App6ath containing the full path to your application.

1.. /rgani0e #our application into features

>ou may want to give the user the possibility to install only some parts of your application. To do this you must organi8e you application into several features. To see the structure of your application select the ,rgani8ation page on the left pane. At this moment" all your files are included into a single feature" called <Main=eature<. >ou will create a new feature that contains the <foo.edi< example file. In the <Main=eature< only the <%otepad.exe< component will be present. Select <6roduct< in the tree and click the <%ew =eature< toolbar button. 'rag and drop the <foo.edi< component in the newly created feature. To make this feature optional Ji.e. to be installed only on #ustom or =ull types of installationK select in the <Install evel< field the <1 J#ompleteK< option. >our organi8ation page should look like this.

=or more details about features and components please see the ,rgani8ation page.

11. Set dialogs to guide t%e user during install

;o to the 'ialogs page. Iere you can select the dialogs that appear during install. In our example" you will add two more dialogs@ A dialog in which the user to choose the type of installation JTypical" #omplete" #ustomK. A dialog for displaying a license agreement text. >ou also will allow the user to choose to view the 2eadMe file or to launch the application at the end of the installation. =or the first goal" right click the *elcome dialog from the left)side pane and choose $Add 'ialog( from the context menu. Select the $SetupType'lg( dialog. =or the second goal" repeat this procedure but select the $ icenseAgreement'lg( dialog from the $Add 'ialog( window. #lick on the 9 0rowse : button from the right)side pane to select from your machine the 2ich Text =ormat file containing the license agreement. =inally" you must add to your package the 2eadMe file for your application Juse the $=iles and =olders( option pageK. Select the $+xit'ialog( dialog from left)side pane. In

the right)side pane" check the $Show <Diew 2eadMe< option( checkboxN you will be prompted to choose the 2eadMe file of your application. #hoose the file you just added to your package. %ext" check the $ aunch Application at the end of installation( checkbox and select from your package the application that will be launched at the end of the installation.

%ote that the user can choose not to see the 2eadMe file or to launch this application.

=or more information please see the 'ialog +ditor page. 0uild and test the package again.

The Advanced Installer project file only contains a description of how to build your MSI installer" and does not actually include any files.

12. Set package name and some more media options

In this step you set the name of the package that will be generated. Select the $Media( page from the left)side pane and navigate to the #onfiguration Settings Tab. Set <My6ackage%ame< in the <MSI name< text field. If you let this field empty" the name of the package will be the same as the name of your project.

=or more details about the available options please see the Media page.

13. Add en ironment aria1les to #our project

et!s suppose your application needs some information stored in an environment variable. In this step you will add to your project this type of variable. In our example" we will add a variable )

<%,T+6A'M6ATI< ) that will contain the path to the folder in which your application will be deployed.

Select $+nvironment( from the $System #hanges( options group. #lick on the 9 %ew Dariable : toolbar button and fill the fields of the newly appeared dialog as in the next screenshot.

=or more information please see the +nvironment Dariables page.

14. Add custom actions to #our installation package

#ustom actions are useful when you need to perform a specific action during installation and there is no other way to do it. The custom action is entirely defined by youN in Advanced Installer you only specify the file that contains it and some parameters for its execution. >ou can add custom actions contained in +L+ files" ' files" D0Script files or a OavaScript files. Select $#ustom Actions( option from the <#ustom 0ehavior< group in order to add a #ustom Action. Select the <Install +xecution Stage< )& <Add 2esources< action group in the left)side pane. #hoose from the toolbar $ aunch installed file(. Select from the =ile6icker dialog the <%otepad.exe< file Jyou included this earlier in your projectK.

In the command line field pass the string <foofile<. The effect is that %otepad will try to open this fileN if <foofile< doesn!t exist on the target machine" %otepad will ask the user whether it should create a new one. This shows the way the command line arguments behave. =or more information please see the #ustom Actions page.

1!. Install and control ser ices

In this step" we will define the services to be installed with your application. >ou can only install services that are part of your package. =irst" use the $=iles and =olders( option to add the service file Ja native *indows serviceK to your project. ;o to the $Services( page from the $2esources( option group.

#lick on the 9 %ew service : toolbar button. Select the service file from the dialog

that appears and fill the service properties fields as in the screenshot below. >ou can control your service or any other service installed on the target machine during installation. The above operations installed both the service and the service control. The following screenshot shows you exactly the control service operation parameters.

= or more

information about this please see the Services page and the Oava Service Installation tutorial.

1$. Add merge modules to #our project

et!s suppose you install an application that reFuires Microsoft # 2untime ibrary. The logic and files that compose this library already exist in the merge module. >ou can include this module in your package and it will be installed with your application. This way" you are sure your application will work on every machine. *ith Advanced Installer it is very easy to add a merge module to your package. #hoose $Merge Modules( from the $2eFuirements( options group #lick on the 9 %ew merge module : toolbar button and browse to your msm file. That!s all?

= or more information please see the Merge Modules page.

1&. Set t%e 2I appearance of #our installation package

In this step we will change the 7I appearance of the package. ;o to the <Themes< page in the <7ser Interface< group. In the <6review< tab you can change the banner showed on the dialogs and the background from the first and the last dialog. >ou can choose one of the Advanced Installer predefined images or you can use one of your own by expanding $More options( and double)clicking $'ialog0itmap( or $0anner0itmap(. =or more information please see the Themes page.

'%e "nd
This concludes our tutorial. To learn more" please read the ,ther anguages tutorial.

2sing '%e Auto 2pdater

This tutorial will guide you step by step in creating and maintaining an install package that uses the Advanced 7pdater. *e will create an install package for the <story.txt< file that we used in the Simple Installation tutorial. If you have an +L+ file at your disposal to which you can easily change the version you could use it instead of the $story.txt( file to complete this tutorial.

1. Create the original install package. 2. Manage the first update 3. Manage the second update 4. Manage a patch

1. Create t%e original install package.

#reate a professional project. %ow create the install package following the same steps as described in the Simple Installation tutorial" but don!t build the package yet. After adding the files to the package it is time to add the auto)update functionality. Switch to the 7pdater by selecting it in the left)side panel. Select the $+nable Advanced 7pdater( checkbox. %ow" you will have to reserve on your site a location for the updates configuration file. >ou will create this file when the first update will be released. =or now" you just have to input the location. et!s suppose you have chosen this location@
http://www.myupdateslocation.com/download/StoryUpdates.txt

+nter it in the $7pdates 72 ( field.

=or deployment simplicity reasons we have used TLT as the extension for the updates configuration file. If you want to use other extensions you might need to configure the MIM+ types on your server to recogni8e that extension. In order to be able to launch the Advanced 7pdater" create a desktop shortcut that will point to the updater.exe file in the package.

;o to the =iles and =olders page. 2ight click on the $updater.exe( file and choose <%ew Shortcut...<. In the newly appeared dialog edit the fields like in the following screen)shot.

If you are using an +L+ file to go through this tutorial instead of creating a shortcut please see an example on how to integrate the updater with your application. Save and build the package. Install the package. #lick on the desktop shortcut. %aturally" no updates are found.

2. Manage t%e first update

=irst you need to create a backup of the original project. After the backup is made you can start modifying it to create a new version. ;o to the 6roduct 'etails Tab page and increase the <6roduct Dersion< Jfor example you can set it to ..E.EK. *hen selecting another page you will prompted about the update method. Answer Major 2pgrade in order to enable the automated upgrade feature.

Modify the story.txt file by changing a few words and eventually add some new files. Suppose the new si8e of <story.txt< is -./1. 2emember this si8e in order to use it as a detection criteria in the updates configuration project. >ou could now release an update which makes these changes. If you are using an +L+ file you can increase it!s version. Save and build the package. After creating a new version of the package is time to create the <Story7pdates.txt< file on the server so the updater will know that new updates are available. #reate a new 7pdates #onfiguration 6roject and configure the first update as showed in the updates tutorial. After generating the updates configuration file place it at the 72 location you specified in the original package. 7se the updater shortcut installed by the original package. >ou will notice that a new update is found. 'ownload and install it. *hen checking for updates again your application should be up to date Jno updates should be foundK. If you receive the "Some of the updates failed to install properly" message after installing an update" most likely you specified an incorrect detection criteria in the 7pdate 6roperties page of the updates configuration project.

3. Manage t%e second update

Modify the story.txt file by adding a new paragraph. It!s new si8e is ./13. 2emember this si8e in order to use it as a detection criteria in the updates configuration project. If you are using an +L+" increase its version again. >ou can now create another update" just like you created the first one. This new package can have the version /.E.E. After generating it place the new version on your server. ,pen your updates configuration project and configure the new update. #heck for updates again. >ou will notice that the first update is not visible anymore" only the second one can be installed. Install the update.

4. Manage a patc%

To create a patch you can try following our patch tutorial. 6atches can also be applied through the Auto 7pdater. Simply configure the patch as update" just like you configure a new version of the package. =or the 7pdater it doesn!t matter if the update is a MSI" +L+ or MS6 file.

'%e "nd
This concludes our tutorial. =or a visual overview of how the updater works" you can follow Iow the 7pdater works article. In this tutorial the file si8e was used as a criteria for detecting whether an update is installed or not. This is because the main file from the package is a TLT file which has no version. *hen using the updater with a real application we recommend using a file version as a criteria. This version is supposed to change for each new release. =or an example of a configuration file that uses this criteria please see@ Sample updates configuration files

'opics

Create Updates File Step by step tutorial describing the creation of an Updates Configuration File. Sample updates configuration files Sample updates configuration file for an ! application.

Creating a 3e+ 2pdates 4ile

This tutorial will guide you step by step in creating and maintaining an 7pdates #onfiguration =ile used by the Auto 7pdater. *e will create an 7pdate 6roject that will have as result the updates configuration file used in the 7pdater Tutorial.

1. Create pro"ect 2. #dd the first update 3. #dd the second update 4. #dd the third update $. %he nd

1. Create project
If Advanced Installer is not currently running" launch it by double)clicking a desktop icon or selecting it from the <Start< menu. *hen the application starts" you will see a dialog where you can choose the type of the project you want to create.

Select $7pdates( & $7pdates #onfiguration( and press the #reate 6roject button. The new project has been created and from now on you will edit it. Save the project and give it the same name used in the updater tutorial ) <Story7pdates<.

2. Add t%e first update

After completing the first part of the updater tutorial you will need to manage the first update. So it is time to configure the project to add information on $story..E.msi( update. 7se the 9 %ew 7pdate : toolbar button. A dialog will pop out allowing you to choose the location of the update file on the disk. Select the new version of your package Jfor example <story..E.msi<K. Select the update in the tree and rename it to $story..E(. 7pload the package to your server and set its 72 in the 'ownload 72 field. In the <Installed 'etection< section set the criteria to <file si8e search<. Select the file which should be checked Jstory.txtK and the expected file si8e after the update J-./1K. The detection criteria should be met after the update is installed. Therefore" it should use the information from the new version of your package.

The description of the update is specified in the 'escription tab.

=or detailed description of the all the I%I entries that are available please see updates configuration file. 0uild the project. The updates configuration file should look something like this@
;aiu; [story2.0] Name=Story 2.0 U !=http://www.myupdateslocation.com/download/story2.0.msi Si"e=#$2%& Ser'er(ileName=story2.0.msi (ile)ath=[*))+, ]story.txt (ileSi"e=-2$# +escription=.his /ixes some spellin0 errors in story.txt /ile.

3. Add t%e second update

To add and configure a new update you can use the same steps as above. This second update includes the first one" so you can configure it to replace the first update. 7se the 9 Add & 2eplaces : toolbar button. A dialog will pop out allowing you to specify the replaced updates. 7pload the package to your server and set its 72 in the 'ownload 72 field. #onfigure the detection criteria for the new si8e of the <story.txt< file J./13" like the example in the 7pdater tutorialK. 0uild the project. The updates file should look something like this@
;aiu; [story$.0] Name=Story $.0 U !=http://www.myupdateslocation.com/download/story$.0.msi Si"e= Ser'er(ileName=story$.0.msi (ile)ath=[*))+, ]story.txt (ileSi"e=2$#% +escription=.his adds a new para0raph. eplaces=*ll [story2.0] Name=Story 2.0 U !=http://www.myupdateslocation.com/download/story2.0.msi Si"e=#$2%& Ser'er(ileName=story2.0.msi (ile)ath=[*))+, ]story.txt (ileSi"e=-2$# +escription=.his /ixes some spellin0 errors in story.txt /ile.

4. Add t%e t%ird update

The last update that is described in the updater tutorial is a patch. Add it to the project and configure it just like the ones before. Since it!s a patch" it can be applied only to the second update. This means that a dependency must be created. 7se the 9 Add & 'ependency : toolbar button. A dialog will pop out allowing you to specify the update on which the current update depends on.

7pload the package to your server and set its 72 in the 'ownload 72 field. #onfigure the detection criteria for the new si8e of the <story.txt< file. 0uild the project.

!. '%e "nd
This concluded the tutorial. After building the project in it!s final state the updates configuration file will look something like this@
;aiu; [story$.-] Name=Story $.U !=http://www.myupdateslocation.com/download/story$.-.msi Si"e=$#2#% Ser'er(ileName=story$.-.msi (ile)ath=[*))+, ]story.txt (ileSi"e=$#%& +escription=.his is a )atch. +epends=story$.0 [story$.0] Name=Story $.0 U !=http://www.myupdateslocation.com/download/story$.0.msi Si"e=2$#%& Ser'er(ileName=story$.0.msi (ile)ath=[*))+, ]story.txt (ileSi"e=2$#% +escription=.his adds a new para0raph. eplaces=*ll [story2.0] Name=Story 2.0 U !=http://www.myupdateslocation.com/download/story2.0.msi Si"e=#$2%& Ser'er(ileName=story2.0.msi (ile)ath=[*))+, ]story.txt (ileSi"e=-2$#

+escription=.his /ixes some spellin0 errors in story.txt /ile.

Integrate licensing feature in 5B projects

This tutorial will guide you in creating a D0 application with licensing and trial support using Advanced Installer. This walkthrough is designed to help you gain a better understanding of how the licensing feature in Advanced Installer works and how you can implement a licensing component into your own project. Throughout this example we!ll create a simple Disual 0asic project using Disual Studio .EEG. ,ur sample application itself will have a simple form but you should find sufficient comments in the underlying code to assist you in implementing this feature into any of your own projects. The project will include a very simple !About! form which will display the licensed state of the application. 0ecause the nature of this walkthrough is to help you understand the licensing process in its entirety we are going to flip backwards and forwards between Advanced Installer and the application code. It!s assumed that you are familiar with the basics of using Disual Studio so these will not be gone into. So with our Disual 0asic project completed as far as we wish to go at present we!ll create a Fuick build in Advanced Installer using the Import Disual Studio 6roject wi8ard and then we will set the licensing options.

1. Create the &isual 'asic pro"ect using &isual Studio 2. Use the #d(anced )nstaller )mport *i+ard for &isual 'asic application 3. Con(ert your pro"ect to nterprise 4. #dd %rial and ,icensing $. Choose %rial -ptions o $.1 %rial -ptions o $.2 #pplication . ,ibrary %ype o $.3 /isplay -ptions o $.4 )ntegration settings summary 0. )ntegrate the ,icensing ,ibrary 1ithin application 2. /one 3 'uild and install 4. 5egister the application 6. Uninstall and Clean3up

1. Create t%e 5isual Basic project using 5isual Studio

7sing Disual Studio .EEG create a Disual 0asic project. Add an menu strip and an About form and save the project.

*e will later add the code that will verify the trial period and registration key.

2. 2se t%e Ad anced Installer Import 6i0ard for 5isual Basic application

,pen Advanced Installer and use the $Disual Studio Application( speciali8ed template. #omplete the wi8ard by selecting the Disual 0asic solution created earlier and you will find your application in =iles and =olders page.

Save the project by using the 9 Save : toolbar button and choose the file name and the destination folder.

3. Con ert #our project to "nterprise

The Disual Studio Import *i8ard created an Advanced Installer Professional project. To use the trial and licensing features we must upgrade the project from Professional to Enterprise. 7se the <6roject< )& <,ptions< menu item to display the options page. In the <6roject Type< page you will be able to update you project to Enterprise.

4. Add 'rial and 7icensing

icensing and trial options can be configured from the icensing page that you will find in the Tools section of the left pane or alternatively you can access it from the <Installation< )& <Tools< )& < icensing< menu. #lick the 9 %ew Trial : toolbar button to add a licensing library to your project.

The licensing library will be placed into the Application Folder and you can see it in the =iles and =olders page. %ote that the name of the library file corresponds with the trial configuration name.

The licensing library name will be used in the application source code so it!s better to leave it in the same folder as the application.

!. C%oose 'rial /ptions

The trial options can be found into the ,ptions and 'isplay tab pages of the < icensing< view. et!s start with the first one.

$.1

%rial -ptions Display Name ) the application name which will be used in the icensing user interface. 0y default it will be the 6roduct %ame you entered during the import wi8ard or changed in the 6roduct 'etails page. Purchase Url ) your *eb Site page that handles purchases. 0y default it will be the <6roduct 72 < specified in the 6roduct 'etails page. Advanced Installer supports several types of trial periods@

%ime ,imited 3 the trial period 1ill end after a predefined number of days ha(e passed since the installation of the product. Uses ,imited 3 the trial period 1ill end after a predefined number of runs of the application. 'oth 3 the trial period 1ill end 1hen one of the abo(e ends.

%ow that we have seen the available types of trial" let!s select <0oth< because it will expire faster. Set the trial period Fuantity into the < imit At< field to a small value" let!s say -E. This way the trial will expire after -E runs or after -E days since installation. =inally in the <,n new version install extend to< field we will set the number of days and uses that we are prepared to extend the trial by when a new version of the application is installed. Set this value to 3 because the user already had some time to try the application in the previous version. ets not choose to support trial extension options to keep thinks simpler. %ow we should specify which kind of application will use the licensing library.

$.2

#pplication . ,ibrary %ype There are several types of library

323bit #7S) 3 supports *in68 or higher -S and can't be used in / 9 enabled applications 323bit Unicode 3 supports *in2k or higher -S and can be used in / 9 enabled applications 043bit Unicode 3 supports any 043bit -S and can be used in / 9 enabled applications

Since we will use the licensing library from a Disual Studio .E-E project which Jsame as DS .EE3B.EEGK creates '+6 enabled applications" let!s use the /.)bit 7nicode version.

$.3 /isplay -ptions

Iere we can control what our registration wi8ard will look like and the freFuency with which it is displayed during our trial period. 6lease note that the display freFuency percentage is applied to the number of times that the application is opened and does not strictly adhere to the choice that you made on the previous tab about the type of trial that you would like to implement. The default is set to /E which means that you will on average see the trial dialog every third time that you open the application. *e will enable the $Show the trial message at first run( option since it is meant for applications that display a license agreement or a welcome message at the first run. >ou can change the default $0anner Image( and $'ialog Image( but keep in mind that they will only be used on operating systems earlier than *indows Dista. $.4 )ntegration settings summary There are three settings that we need in order to integrate out D0 application with Advanced Installer icensing@

library name 3 1e 1ill need it to identify 1hich library 1ill be loaded 1hen the application starts

platform type 3 1e should make sure that our &' application is compatible 1ith the selected platform :323bit;. library key 3 specified in the <5egistration< tab page and used 1hen 1e 1ill call the library functions

%ow we are ready to return to Disual Studio and integrate the Advanced Installer icensing library.

$. Integrate t%e 7icensing 7i1rar# +it%in application

In our Disual Studio project lets set the corresponding platform of the D0 application. So into Disual Studio go to <6roject< )& <6roperties< )& <#ompile< )& <Advanced #ompile ,ptions< dialog and set the target #67 to xG4. Into the =orm-.vb source file add the following code snippets@ 'on!t forget to replace the ibrary Cey from the code snippet with the one from the Advanced Installer project & icensing & 2egistration page.
,mports System ,mports System. untime.,nteropSer'ices ... 1 .his /unction does all the wor2 3+ll,mport45.rial.dll56 7ntry)oint:=5 eadSettin0sStr56 8harSet:=8harSet.*nsi9: ; )ri'ate Shared (unction ,nit.rial4<y=al a>ey8ode *s Strin06 <y=al a?@nd *s ,nt)tr9 *s U,nte0er 7nd (unction 1 Use this /unction to re0ister the application when the application is runnin0 3+ll,mport45.rial.dll56 7ntry)oint:=5+isplay e0istrationStr56 8harSet:=8harSet.*nsi9: ; )ri'ate Shared (unction +isplay e0istration4<y=al a>ey8ode *s Strin06 <y=al a?@nd *s ,nt)tr9 *s U,nte0er 7nd (unction 1 .he 2!iArary>ey is meant to pre'ent unauthori"ed use o/ the liArary. 1 +o not share this 2ey. eplace this 2ey with your own /rom *d'anced ,nstaller 1 proBect : !icensin0 : e0istration : !iArary >ey )ri'ate Shared 2!iArary>ey *s Strin0 = 5$(C&2#&<$<07-D#%0&8<8E(%-2+C0<D+07(E2#287(*D270$2$C+C-%2*(C0+<+#2E7+% %D(<<D05 1 .he re0ister state o/ the application which is computed when the /orm is loaded )ri'ate re0istered *s <oolean )ri'ate SuA (orm-;!oad4<y=al sender *s System.FABect6 <y=al e *s System.7'ent*r0s9 ?andles Gy<ase.!oad .ry +im )roc *s )rocess = )rocess.Het8urrent)rocess49 1 .his call will display the trial dialo0s i/ needed +im ret = ,nit.rial42!iArary>ey6 )roc.Gain@indow?andle9

1 0 return code means that the application is re0istered usin0 a 'alid code6 otherwise is in trial ,/ ret = 0 .hen re0istered = .rue 7nd ,/ 8atch ex *s 7xception Gessa0e<ox.Show4ex..oStrin0499 )rocess.Het8urrent)rocess49.>ill49 7nd .ry 7nd SuA )ri'ate SuA +o e0ister49 .ry +im )roc *s )rocess = )rocess.Het8urrent)rocess49 +im ret = +isplay e0istration42!iArary>ey6 )roc.Gain@indow?andle9 1 0 return code means that the application was already re0istered or it 1 has Bust Aeen re0istered6 otherwise is in trial ,/ ret = 0 .hen re0istered = .rue 7nd ,/ 8atch ex *s 7xception Gessa0e<ox.Show4ex..oStrin0499 8lose49 7nd .ry 7nd SuA )ri'ate SuA *Aout.oolStripGenu,tem;8lic24<y=al sender *s System.FABect6 <y=al e *s System.7'ent*r0s9 ?andles *Aout.oolStripGenu,tem.8lic2 +im dl0 *s *Aout<ox- = New *Aout<ox1 Set the aAout Aox memAer to the re0istered state computed when the application loaded dl0.re0istered = Ge.re0istered 1 +isplay the dl0.Show49 7nd SuA *Aout Aox

)ri'ate SuA e0ister.oolStripGenu,tem;8lic24<y=al sender *s System.FABect6 <y=al e *s System.7'ent*r0s9 ?andles e0ister.oolStripGenu,tem.8lic2 ,/ re0istered .hen Gessa0e<ox.Show45.he application is already re0istered.56 5 e0istered56 Gessa0e<ox<uttons.F>6 Gessa0e<ox,con.,n/ormation9 7lse +o e0ister49 7nd ,/ 7nd SuA

Into the About0ox-.vb source file add the following code snippets@
... )uAlic re0istered *s <oolean )ri'ate SuA *Aout<ox-;!oad4<y=al sender *s System.FABect6 <y=al e *s System.7'ent*r0s9 ?andles Gy<ase.!oad ...

,/ Ge.re0istered .hen Ge..ext<ox+escription..ext = 5re0istered I than2 you5 7lse Ge..ext<ox+escription..ext = 5trial5 7nd ,/ 7nd SuA

>ou have now successfully integrated the licensing feature into your project. >ou will not be able to test the application until you install the MSI package. After that you can run the application from its install location. If you want to run the application from Disual Studio you will have to copy the <Trial.dll< library from the install location to the <bin< & <'ebug< andBor <bin< & <2elease< folders under the Disual Studio project folder.

&. 8one 9 Build and install

%ow that we have integrated the licensing functionality lets go back to Advanced Installer and build the installation package. #lick on the 9 0uild : toolbar button and a $0uild 6roject( dialog will appear showing you the build evolution. ,nce the build is complete" click on the 9 2un : toolbar button. A setup wi8ard will appear that will guide you through the install process. #ongratulations? >ou have successfully created your licensed application. 0y default" the application file will be installed under #@A6rogram =ilesA>our #ompanyA. 0rowse to that folder in *indows +xplorer and run the application.

#lick the 9 Try : button and the D0 form should appear. In the $About( dialog the trial message should be displayed.

*.

Register t%e application

After -E tries Jor days ) remember the trial type usedK the trial period must expire.

At this point the user needs to register the application since we didn!t enable the trial extension option. 2egistration codes can be generated from the Advanced Installer )& icensing )& 2egistration page by using the $;enerate 2egistration Ceys( link. In the $;enerate 2egistry Ceys( dialog generate any number of keys you want. The keys will be saved into a file from where you can easily pick one when you want to sent it to a user. %ext time you generate registration keys you should fill the $Cey or CeyI' number to start from( with the last key that you have generated previously. That will ensure that the generated keys have not been generated before. #opy a registration code from the file you have just saved. %ow" return to the trial expired page and click 9 2egister : and paste the registration code Jif it wasn!t already detected in the clipboardK into the text area from the 2egistration page.

#lick 9 #ontinue : to validate the registration key.

#lick 9 #ontinue : to exit the 2egistration *i8ard and resume the D0 application. The application is now registered and we can see it in the $About( dialog.

-. 2ninstall and Clean9up

'uring testing or development you may want to remove any trace of the application to reproduce the conditions before the first installation. =or that you must@

Uninstall the package 3 that 1ill delete the installed files. /elete the registration code from registry 3 by default it is sa(ed in Current User=Soft1are=>our Company=>our 9roduct=5egistration ?ey and can be configured from the #d(anced )nstaller 3@ <,icensing< 3@ <5egistration< page. /elete the trial information from the system 3 in #d(anced )nstaller 3@ <,icensing< page right3click on the trial configuration and choose <%esting< @ <5emo(e %rial )nfo< :#d(anced )nstaller must ha(e administrator rights for this operation to succeed;.

That concludes our tutorial. >ou may also find useful our sample licensing projects.

'%e "nd
This concludes our tutorial.