QuickStarts

Updater Application Block - Version 2.0

March 2005

Summary: This quick start chapter provides walk through for common scenarios to aid your understanding of the application block.

The Updater Application Block includes a number of QuickStart sample applications that you can use to test common scenarios and aid your understanding of the application block. All QuickStarts are available in both Visual Basic .NET and Visual C# .NET.

The Updater Application Block includes the following QuickStarts, in order of ascending complexity:

• Simple AppStart QuickStart
• Manual InProc QuickStart
• Auto InProc QuickStart
• MSI QuickStart
• No-Touch Deployment QuickStart

Install the QuickStarts

After you install the Updater Application Block, you can install the QuickStart applications by using the Deploy QuickStarts option on the QuickStarts submenu. This creates the Web folders required by the QuickStart samples. You can remove the Web folders from your computer by using the Uninstall QuickStarts option on the QuickStarts submenu.

Note   The software requirements for the Updater Application Block are listed in the Introduction to the Updater Application Block.

Configure the QuickStarts

Note   You will need to modify the QuickStarts to successfully build with Enterprise Library-June 2005. Follow the steps in the "Modify the Updater Application Block to Use Enterprise Library-June 2005" section in the Developing Applications with the Updater Application Block.

The install script for the QuickStarts configures the Web folders in Internet Information Server (IIS) for the client applications to download the manifests from. However, if you are using IIS version 6.0, you must perform some additional configuration steps to enable the downloading of specific file types.

Note   The Deploy Quickstarts script disables filtering of .exe, .dll and .msp files. You can manually disable filtering of these files by performing the following steps.

To disable filtering of .exe, .dll and .msp files

1. Open the Internet Information Services MMC console.
2. Right-click the Updater2QuickStarts directory, and then click Properties.
3. On the HTTP Headers page, click Mime Types, and then click New.
4. In the Extension box, type exe.
5. In the MIME type box, type a valid MIME type (for example, binary.) If you define a MIME type that has already been defined at a higher level, you are prompted to select the level where the MIME type should reside.
6. Click OK.
7. For the .dll and .msp file name extensions repeat steps 4 through 6.

Simple AppStart QuickStart

This QuickStart demonstrates using an AppStart tool that enables updating of files either before the client application launches or after it exits.

When the user starts the AppStart application, it checks the server for updates. If any updates are present, the user is given the option to install them. If the user chooses to install the updates, the update process runs, and then the AppStart application launches the client application using the System.Diagnostics.Process class.

This QuickStart demonstrates the use of a bootstrap application for initiating updates and then starting the main client application. It also demonstrates checking for updates, downloading files, and running activation processors.

Design of the Simple AppStart QuickStart

The following procedure describes how the Simple AppStart QuickStart application runs:

1. The user runs the application, which executes the SimpleAppStart assembly.
2. The Main method uses a mutex to verify that no other instances of this application are running, and then it checks the application configuration to determine whether the update should run before or after the client application runs. The QuickStart is configured to update the application prior to execution.
3. The SimpleAppStart assembly uses the ApplicationUpdaterManager to check for updates on the server at the URI specified in the application configuration.
4. If updates for this client application are found, the user is given the option to install them.
5. The Application.Location property for each manifest is updated. The value of the location element from the manifest is combined with the path of the executing application to generate a valid local path on the client computer. This technique ensures that the path defined in the manifest on the server is valid on the client computer.
6. If the user wants to install the updates, the ApplicationUpdaterManager downloads the new files specified in the manifest to the client computer. These files are the following:
   1. SimpleApplication.exe
7. The SimpleAppStart assembly uses the ApplicationUpdaterManager to run the ApplicationDeployProcessor activation processor specified in the manifest. This processor copies the files from the download location to the destination location.
8. The SimpleAppStart assembly retrieves the client application executable path and file name from the application configuration and starts a new process to run the updated client application.
9. The SimpleAppStart assembly exits, leaving the client application running.

Running the Simple AppStart QuickStart

To review the execution of the Simple AppStart QuickStart, perform the following steps:

1. On the taskbar, click Start, point to Programs, point to Microsoft patterns & practices, point to Updater Application Block v2, point to QuickStarts, point to Simple AppStart, and then click either CS Simple AppStart QuickStart or VB Simple AppStart QuickStart.
2. On the Build menu, click Rebuild Solution.
3. On the Debug menu, click Start.
4. When asked to apply the update, click No, and note that Simple Application base Version 1.0 runs. Close the client application.
5. On the Debug menu, click Start.
6. When asked to apply the update, click Yes. The QuickStart runs as described in the Design of Simple AppStart QuickStart. Note that after the download and activation, Simple Application updated Version 2.0 runs.

Note   By design, this QuickStart downloads the new version only once because information stored in the SimpleAppStart\Client\SimpleAppStart\bin\Debug\UAB folder identifies that the update has been applied. To re-run the QuickStart, you must delete the UAB folder.

Manual InProc QuickStart

This QuickStart demonstrates using the Updater Application Block as an in-process component to provide the user with the ability to update an application on demand.

When the user clicks the Update button, the application checks whether updates are available, and if so, gives the user the option to install them. The updates are installed using the asynchronous BeginDownload method enabling the user to continue working in the client application.

The manifest file defines that when the client application exits, the updates should be copied to the working folder.

This QuickStart demonstrates using the download and activation events. It also demonstrates the WaitForApplicationExitProcessor and ApplicationDeployProcessor activation processors and uses the PostApplicationExitActivationProcess tool to run the pending activation processor after the application exits.

Design of the Manual InProc QuickStart

The following procedure describes how the Manual InProc QuickStart application runs:

1. The user runs the client application and clicks the Update button to initiate the update process.
2. The client application subscribes to the download and activation events exposed by the ApplicationUpdaterManager.
3. The client application uses the ApplicationUpdaterManager to check for updates on the server at the URI specified in the application configuration.
4. If updates for this client application are found, the user is given the option to install them. If no updates are found, the user is informed and can continue working with the application.
5. If the user wants to install the updates, the ApplicationUpdaterManager starts an asynchronous download of the new files specified in the manifest to the client computer. These files are the following:
   1. ManualInproc.exe
6. When the DownloadCompleted event is raised, the client application uses the ApplicationUpdaterManager to start the activation process defined in the manifest.
7. The WaitForApplicationExitProcessor PrepareExecution method starts a new process to run the PostApplicationExitActivationProcess.exe tool that waits for the application to exit. The PrepareExecution method then throws the ActivationPausedException exception.
8. This exception raises the ActivationInitializationAborted event in the client application and the user is informed that the client application must be restarted to complete the update process.
9. When the user exits the client application, the PostApplicationExitActivationProcess tool calls the ApplicationUpdaterManager ResumePendingUpdates method. This method resubmits the pending activation task and the ActivationDeploy activation processor copies the downloaded files to the destination location specified in the manifest.

Running the Manual InProc QuickStart

To review the execution of the Manual InProc QuickStart, perform the following steps:

1. On the taskbar, click Start, point to Programs, point to Microsoft patterns & practices, point to Updater Application Block v2, point to QuickStarts, point to Manual InProc, and then click either CS Manual InProc QuickStart or VB Manual InProc QuickStart.
2. On the Build menu, click Rebuild Solution.
3. Using Windows Explorer, navigate to the QuickStarts\cs\ManualInproc\Client\ManualInproc\bin\Debug folder or the QuickStarts\vb\ManualInproc\Client\ManualInproc\bin folder and double-click ManualInproc.exe.

   Note that this is base version 1.0.

4. Close ManualInprocForm, and then close Windows Explorer.
5. On the Debug menu, click Start.
6. Click Update, and then click Yes in the Update message box.

   Note that the download and activation events listed on the form as they occur.

   Note that the PostApplicationExitActivationProcess assembly is started as a separate process.

7. In the Manual Inproc Updates message box, click OK.
8. Review the list of events that have been raised, and then click Exit.
9. Using Windows Explorer, navigate to the QuickStarts\cs\ManualInproc\Client\ManualInproc\bin\Debug folder or the QuickStarts\vb\ManualInproc\Client\ManualInproc\bin folder and double-click ManualInproc.exe.

   Note that this is the updated version 2.0.

10. Close ManualInprocForm, and then close Windows Explorer.

Note   By design, this QuickStart downloads the new version only once because information stored in the ManualInproc\Client\ManualInproc\bin\Debug\UAB folder identifies that the update has been applied. To re-run the QuickStart, you must delete the UAB folder.

Auto InProc QuickStart

This QuickStart demonstrates using the Updater Application Block as an in-process component to automatically update an application whenever new updates are available when the application is running.

When the application starts, a new thread is created that periodically polls the server for updates. This ensures that the polling process does not block the client application. Because the manifest defines that hash comparisons for partial updates should be used, the hash value defined in the manifest for each download file is compared to the computed hash value of the current file on the client computer. If the hashes match, the file is removed from the list of files to download.

When new updates are found, the user is asked whether to install the updates. If the user chooses to install the updates, the update process proceeds as usual.

The manifest file defines that when the client application exits, the updates should be copied to the working folder.

This QuickStart demonstrates using the download and activation events. It also demonstrates the WaitForApplicationExitProcessor and ApplicationDeployProcessor activation processors and uses the PostApplicationExitActivationProcess tool to tool to run the pending activation processor after the application exits.

Design of the Auto InProc QuickStart

The following procedure describes how the Auto InProc QuickStart application runs:

1. The user runs the client application and a new thread is started that subscribes to the ApplicationUpdaterManager download and activation events.
2. The new thread checks the server for available updates at the URI specified in the application configuration every 10 seconds.
3. When updates for this client application are found a hash comparison is performed to check whether the update files available on the server are different than the currently installed files on the client computer. The ManifestManager uses the Enterprise Library Cryptography class to compare the hash value defined in the manifest for each download file with the computed hash value of the file on the client computer. If they match, the file is removed from the list of files to download.
4. The user is given the option to install the updates. If the user wants to install the updates, the ApplicationUpdaterManager starts the download to transfer the new files specified in the manifest to the client computer. These files are the following:
   1. AutoInproc.exe
5. When the download is complete, the client application uses the ApplicationUpdaterManager to start the activation process defined in the manifest.
6. The WaitForApplicationExitProcessor PrepareExecution method starts a new process to run the PostApplicationExitActivationProcess.exe tool that waits for the application to exit, and then the method throws the ActivationPausedException exception.
7. This exception raises the ActivationInitializationAborted event in the client application and the user is informed that the client application must be restarted to complete the update process.
8. When the user exits the client application, the PostApplicationExitActivationProcess tool calls the ApplicationUpdaterManager ResumePendingUpdates method. This method resubmits the pending activation task, and the ActivationDeploy activation processor copies the downloaded files to the destination location specified in the manifest.

Running the Auto InProc QuickStart

To review the execution of the Auto InProc QuickStart, perform the following steps:

1. On the taskbar, click Start, point to Programs, point to Microsoft patterns & practices, point to Updater Application Block v2, point to QuickStarts, point to Auto InProc, and then click either CS Auto InProc QuickStart or VB Auto InProc QuickStart.
2. On the Build menu, click Rebuild Solution.
3. Using Windows Explorer, navigate to the QuickStarts\cs\AutoInproc\Client\AutoInproc\bin\Debug folder or the QuickStarts\vb\AutoInproc\Client\AutoInproc\bin folder and double-click AutoInproc.exe.

   Note that this is base version 1.0.

4. Close AutoInprocForm, and then close Windows Explorer.
5. On the Debug menu, click Start.
6. When the Update message box appears, click No.

   Note that nothing happens until the next polling interval when the Update message box appears again.

7. In the Update message box, click Yes.

   Note that the download and activation events are listed on the form as they occur.

   Note that the PostApplicationExitActivationProcess assembly starts as a separate process.

8. In the Auto Inproc Updates message box, click OK.
9. Review the list of events that have been raised, and then click Exit.
10. Using Windows Explorer, navigate to the QuickStarts\cs\AutoInproc\Client\AutoInproc\bin\Debug folder or the QuickStarts\vb\AutoInproc\Client\AutoInproc\bin folder and double-click AutoInproc.exe.

    Note that this is the updated version 2.0.

11. Close AutoInprocForm, and then close Windows Explorer.

Note   By design, this QuickStart downloads the new version only once because information stored in the AutoInproc\Client\AutoInproc\bin\Debug\UAB folder identifies that the update has been applied. To re-run the QuickStart, you must delete the UAB folder.

MSI QuickStart

This QuickStart demonstrates how to use the Updater Application Block to perform installations using the Windows Installer. It shows how to use full distribution packages (.msi files) that can perform a complete installation of a product and how to use an update package (.msp file) that only contains the resources needed to update a product.

From the client application point of view, the code to install the .msi file is the usual code. The primary manifest defines two included manifests. To ensure that only one manifest is used per update process, the Apply property of only the first unapplied manifest is set to true on each execution of the code.

Each manifest includes an activation element that specifies to use the MSIProcessor activation processor to install the appropriate application. The contents of each activation element vary depending on the functionality required. For example, the setup configuration uses an installType of Install and identifies an .msi package, whereas the patch configuration uses an installType of Patch and identifies an .msp package.

Each activation element specifies to use the MSIProcessor defined in the Microsoft.ApplicationBlocks.Updater.ActivationProcessors namespace. The Init method of this processor stores the contents of the activation element in private fields. The Execute method instantiates a WindowsInstaller.Installer object. It then calls the appropriate method of the Installer object according to the installType in the configuration, passing any required parameters, such as the name of the package to run and the action to perform.

This QuickStart demonstrates the use of the MSIProcessor and how to use included manifests to implement application versioning.

Design of the MSI QuickStart

The following procedure describes how the MSI QuickStart application executes on the first run:

1. The user runs the bootstrap application, and the ApplicationUpdaterManager checks the server for available updates at the URI specified in the application configuration.

   The primary manifest, Msi_setup.xml, contains an includedManifests element that defines to include the Msi_patch.xml and Msi_remove.xml manifests.

2. Because the first run of the application should install only the application, the client application sets the Apply property of the first manifest, Msi_setup.xml, to true.
3. The client application subscribes to the download and activation events, and then it initiates the download process, which downloads the SimpleApplicationSetup.msi file specified in the Msi_setup.xml manifest.
4. If the download is successful, the client application initiates the activation process defined in the downloaded manifest.

   This manifest defines to use the MSIProcessor activation processor with the configuration shown in the following code sample.

   <config>
       <installType>Install</installType>
       <packagePath>SimpleApplicationSetup.msi</packagePath>
       <propertyValues>ACTION=INSTALL</propertyValues>
       <uiLevel>msiUILevelProgressOnly</uiLevel>
   </config>
     

5. The Init method of the MSIProcessor stores these configuration settings in class variables.
6. The Execute method of the MSIProcessor creates an instance of the CWindowsInstaller class and calls the InstallProduct method of the class.
7. The downloaded .msi file is executed on the client computer.
8. A new process is then started to run the newly installed application.

The following procedure describes how the MSI QuickStart application executes on the second run:

1. The user runs the bootstrap application, and the ApplicationUpdaterManager checks the server for available updates at the URI specified in the application configuration.

   The primary manifest, Msi_setup.xml, contains an includedManifests element that defines to include the Msi_patch.xml and Msi_remove.xml manifests.

2. Because the primary manifest has been applied, the Manifests array contains only the Msi_patch.xml and Msi_remove.xml manifests. The client application sets the Apply property of the first manifest in the array, Msi_patch.xml, to true.
3. The client application subscribes to the download and activation events, and then it initiates the download process, which downloads the SimpleApplication.msp file specified in the Msi_patch.xml manifest.
4. If the download is successful, the client application initiates the activation process defined in the downloaded manifest.

   This manifest defines to use the MSIProcessor activation processor with the configuration shown in the following code sample.

   <config>
       <installType>Patch</installType>
       <packagePath>SimpleApplication.msp</packagePath>
       <propertyValues>REINSTALL=ALL REINSTALLMODE=omus</propertyValues>
       <uiLevel>msiUILevelProgressOnly</uiLevel>
   </config>
     

5. The Init method of the MSIProcessor stores these configuration settings in class variables.
6. The Execute method of the MSIProcessor creates an instance of the CWindowsInstaller class and calls the ApplyPatch method of the class.
7. The downloaded .msp file is executed on the client computer.
8. A new process is then started to run the newly patched application.

The following procedure describes how the MSI QuickStart application executes on the third run:

1. The user runs the bootstrap application and the ApplicationUpdaterManager checks the server for available updates at the URI specified in the application configuration.

   The primary manifest, Msi_setup.xml, contains an includedManifests element that defines to include the Msi_patch.xml and Msi_remove.xml manifests.

2. Because the primary and first included manifests have been applied, the Manifests array contains only the Msi_remove.xml manifest. The client application sets the Apply property of the first manifest in the array, Msi_remove.xml, to true.
3. The client application subscribes to the download and activation events, and then it initiates the download process, which downloads the SimpleApplicationSetup.msi file specified in the Msi_remove.xml manifest.
4. If the download is successful, the client application initiates the activation process defined in the downloaded manifest.

   This manifest defines to use the MSIProcessor activation processor with the configuration shown in the following code sample.

   <config>
       <installType>Remove</installType>
       <propertyValues>REMOVE=ALL</propertyValues>
       <uiLevel>msiUILevelProgressOnly</uiLevel>
       <productCode>{896869AA-5628-4E7B-9F1D-5FFD1A1DE5D7}</productCode>
   </config>
     

5. The Init method of the MSIProcessor stores these configuration settings in class variables.
6. The Execute method of the MSIProcessor creates an instance of the CWindowsInstaller class and uses a helper function to initiate the uninstall process.
7. The downloaded .msi file is executed on the client computer and the application removed.

Running the MSI QuickStart

To review the execution of MSI QuickStart, perform the following steps:

1. On the taskbar, click Start, point to Programs, point to Microsoft patterns & practices, point to Updater Application Block v2, point to QuickStarts, point to MSI, and then click either CS MSI QuickStart or VB MSI QuickStart.
2. On the Build menu, click Rebuild Solution.
3. On the Debug menu, click Start.

   You will see the Windows Installer running to install the application and then the installed application will run. Note that this is the original version of SimpleApplication.

4. Close Form1, and then in the command window, press Enter.
5. On the Debug menu, click Start.

   You will see the Windows Installer running to patch the application and then the updated application will run. Note that this is the patched version of SimpleApplication.

6. Close Form1, and then in the command window, press Enter
7. On the Debug menu, click Start.

   You will see the Windows Installer running to remove the application.

8. In the command window, verify that the application has been uninstalled and then press Enter.
9. On the Debug menu, click Start.

   You will be informed that the application has been uninstalled.

Note   By design, this QuickStart will attempt the update process only three times (install, patch, and remove) because information stored in the MSI\Client\MSI\bin\Debug\UAB folder identifies the updates that have been applied. To re-run the QuickStart, you must delete the UAB folder.

No-Touch Deployment QuickStart

This QuickStart demonstrates no-touch deployment of a bootstrap application that uses the Updater Application Block to install and update the client application.

On the first use, the launch application is downloaded from a URI on the Web server and uses the bootstrap assembly to download and run the client application. On subsequent uses, the user will start the bootstrap application. The bootstrap application will check for and apply updates before starting the client application.

Design of the No-Touch Deployment QuickStart

The following procedure describes how the No-Touch Deployment QuickStart application executes:

1. The user opens Internet Explorer and navigates to the launch application executable.
2. The launch assembly creates an AppStart folder on the desktop and extracts the AppStart assembly files to that folder.
3. The launch assembly starts a new process that runs the AppStart application that has been downloaded to the AppStart folder on the client computer.
4. The AppStart assembly uses the ApplicationUpdaterManager to check for updates on the server at the URI specified in the application configuration and prompts the user to update the SimpleApplication.
5. If the user wants to install the updates, the ApplicationUpdaterManager downloads the new files specified in the manifest to the client computer. These files are the following:
   1. SimpleApplication.exe
6. The AppStart assembly uses the ApplicationUpdaterManager to run the ApplicationDeployProcessor activation processor specified in the manifest. This processor copies the files from the download location to the location specified in the manifest.
7. The AppStart assembly starts a new process to run the updated client application.
8. The AppStart process exits, leaving the client application running.

Configuring the No-Touch Deployment QuickStart

To configure code access security for the No-Touch Deployment QuickStart, perform the following steps:

1. Open the Visual Studio .NET 2003 command prompt.
2. Type mscorcfg.msc, and then press Enter.
3. In the .NET Configuration 1.1 console, in the left pane, click Runtime Security Policy.
4. In the right pane, click Adjust Zone Security.
5. In the Security Adjustment Wizard, click Make changes to this computer, and then click Next.
6. Click Local Intranet, move the slider to Full Trust, and then click Next.
7. Review the summary of changes, and then click Finish.
8. Close the .NET Configuration 1.1 console.
9. Close the Visual Studio .NET 2003 command prompt.

Running the No-Touch Deployment QuickStart

To review the execution of No-Touch Deployment QuickStart, perform the following steps:

1. On the taskbar, click Start, point to Programs, point to Microsoft patterns & practices, point to Updater Application Block v2, point to QuickStarts, point to No-Touch Deployment, and then click either CS No-Touch Deployment QuickStart or VB No-Touch Deployment QuickStart.
2. On the Build menu, click Rebuild Solution.
3. Using Internet Explorer, browse to http://localhost/Updater2QuickStarts/cs/NoTouchDeployment/Client/NoTouchDeploymentStub/bin/Debug/NoTouchDeploymentStub.exe or http://localhost/Updater2QuickStarts/vb/NoTouchDeployment/Client/NoTouchDeploymentStub/bin/NoTouchDeploymentStub.exe.
4. In the command prompt window, type Y, and then press Enter.
5. When the SimpleApplication window appears, click Exit.
6. Show the desktop and note that an AppStart folder has been created. This folder contains the bootstrap application, the client application executable, and the supporting files.
7. Users can now run the bootstrap application directly from that location. This application will check for and apply updates before running the client application.

Note   By design, this QuickStart downloads the new version only once because information stored in the NoTouchDeployment\Client\NoTouchDeployment\bin\Debug\UAB folder identifies that the update has been applied. To re-run the QuickStart, you must delete the UAB folder.

Start | Previous