Updater Application Block Version 2.0 FAQ

Updater Application Block Version 2.0 - Home Page

Microsoft Corporation

September 2005

Summary

This page answers frequently asked questions about the Updater Application Block version 2.0.

Contents

Using Enterprise Library-June 2005

• How do I modify the Updater Application Block to use Enterprise Library-June 2005?

Configuration

• How do I provide multiple updates available on the server for download?
• Do I have to include the full path in the source attribute of the File element in Manifest.xml?
• How should I change the Manifest.xml file so the updater knows there is an update available?
• How do I provide partial updates using file hash comparison?

Deployment

• How do I resolve the "Specified cast not valid" error message that I receive when BITSDownloader runs?
• How do I resolve the "System.UnauthorizedAccessException" message that I receive while using UAB in my Web application?
• How do I remove the earlier version folders from the client computer?
• How do I resolve the "Server doesn't support Range Header" message that I receive during setup?
• Why does IIS 6.0 block requests for some file types that are requested by the updater?
• How do I resolve "The client does not have sufficient rights to the requested server object" error message that I receive when I attempt to download the .Config files with Updater? Why does IIS 6.0 block requests for some file types?

Downloader

• How do I use IBackgroundCopyJob2 to send credential information the server? Are there any samples available?
• How can I provide the proxy server information to download the manifest information at run time?

Processor

• How do I perform certain operations after the WaitForApplicationExit processor installs all files in the client application folder?

Using Enterprise Library-June 2005

How do I modify the Updater Application Block to use Enterprise Library-June 2005?

The Updater Application Block needs to be modified to use Enterprise Library-June 2005. You must perform the following steps:

1. Download Enterprise Library-June 2005.
2. Install and compile the Enterprise Library.
3. Open the Visual Studio Updater.sln solution file in Visual Studio .NET 2003. On the taskbar, click Start, point to Programs, point to Microsoft patterns & practices, point to Updater Application Block v2, and then click CS Application Updater Solution or VB Application Updater Solution.
4. If the Common project is unavailable, remove the project from the solution. To do this, right-click on the Common project and select Remove. Next, right click on the Updater Solution, point to Add, and select Existing Project. Browse to the Enterprise Library-June 2005 Common project file (by default, located in C:\Program Files\Microsoft Enterprise Library June 2005\src\Common)
5. Repeat Step 4 for the Configuration project. By default, it is located in C:\Program Files\Microsoft Enterprise Library June 2005\src\Configuration.
6. Repeat Step 4 for the Configuration.Design project. By default, it is located in C:\Program Files\Microsoft Enterprise Library June 2005\src\Configuration\Design).
7. Repeat Step 4 for the Security.Cryptography project. By default, it is located in C:\Program Files\Microsoft Enterprise Library June 2005\src\Security\Cryptography).
8. Repeat Step 4 for the Security.Cryptography.Configuration.Design project. By default, it is located in C:\Program Files\Microsoft Enterprise Library June 2005\src\Security\Cryptography\Configuration\Design).
9. In the solution explorer, expand the References folder under the ActivationProcessors project. Remove references to the following projects. To do this, right-click on the project and select Remove:
   • Common
   • Configuration
   • Security.Cryptography

   Add references to the following projects. To do this, right-click on References and select Add Reference. Click on the Projects tab, select the following projects, and click OK:

   • Microsoft.Practices.EnterpriseLibrary.Common
   • Microsoft.Practices.EnterpriseLibrary.Configuration
   • Microsoft.Practices.EnterpriseLibrary.Security.Cryptography
10. Repeat Step 9 for the Downloaders project. Add references to the following projects:
    • Microsoft.Practices.EnterpriseLibrary.Common
    • Microsoft.Practices.EnterpriseLibrary.Configuration
11. Repeat Step 9 for the Updater project. Add references to the following projects:
    • Microsoft.Practices.EnterpriseLibrary.Common
    • Microsoft.Practices.EnterpriseLibrary.Configuration
    • Microsoft.Practices.EnterpriseLibrary.Security.Cryptography
12. Repeat Step 9 for the Updater.Configuration.Design project. Add references to the following projects:
    • Microsoft.Practices.EnterpriseLibrary.Common
    • Microsoft.Practices.EnterpriseLibrary.Configuration
    • Microsoft.Practices.EnterpriseLibrary.Configuration.Design
    • Microsoft.Practices.EnterpriseLibrary.Security.Cryptography
    • Microsoft.Practices.EnterpriseLibrary.Security.Cryptography.Configuration.Design
13. Build the solution. On the toolbar, select Build Solution from the Build menu.

To test, you should run the QuickStarts. First, you will need to perform the steps above for each Quickstart and then you can build and run the QuickStart.

Configuration

How do I provide multiple updates available on the server for download?

To provide multiple updates available on the server for download, perform these steps:

1. Create a separate manifest file for each update.
2. Create an entry for each manifest file in the main manifest file (Manifest.xml).
3. Modify the manifestID attribute for the update to be downloaded.

The next sections describe each step.

Create a Separate Manifest file for Each Update

Use the manifest editor to create a separate manifest file for each update.

Example:

File: msi_patch.xml

<manifest  manifestid="{C18DC1E6-001C-4d5b-9A84-DD3E1C580552}" 
    mandatory="False"
      xmlns="urn:schemas-microsoft-com:PAG:updater-application-block:v2:manifest">
        <description> Patch the simple application </description> 
    <application applicationid="{215E1AD7-9ABA-432f-A952-24BABA556850}"> </application> 
    <entrypoint file="" parameters=""> </entrypoint> 
    <location>.\..\..</location> 
    <files base="http://localhost/Updater2QuickStarts/cs/msi/server/"> </files> 
    <file source="SimpleApplication.msp"> 
    </files> 
    <activation>
    <tasks>
    <task
    type="Microsoft.ApplicationBlocks.Updater.ActivationProcessors.MsiProcessor,
  Microsoft.ApplicationBlocks.Updater.ActivationProcessors" name="MSIProcessor"\>
    <config>
    <installtype>Patch</installtype>
    <packagepath>SimpleApplication.msp</packagepath>
  <propertyvalues>REINSTALL=ALL REINSTALLMODE=omus</propertyvalues>
    <uilevel>msiUILevelProgressOnly</uilevel>
    </config>
    </task>  
     </tasks>  
    </activation> 
    </manifest> 
  

Create an Entry for Each Manifest File in the Main Manifest File (Manifest.xml)

Use the manifest editor to include references for all manifest files related to application update. The related manifest files should be included under the <includemanifest> element.

Example:

File: Manifest.xml

      <manifest manifestid="{311085F7-9320-4318-9A67-9BE32F04E933}" xmlns="urn:schemas-microsoft-com:PAG:updater-application- block:v2:manifest">   
              mandatory="False" 
       xmlns="urn:schemas-microsoft-com:PAG:updater-application-block:v2:manifest">
      <description>Install the simple application</description>
    <application applicationid="{215E1AD7-9ABA-432f-A952-24BABA556850}">
    <entrypoint file="" parameters=""/>
      <location>.\..\..</location>
        </application>
        <files base="http://localhost/Updater2QuickStarts/cs/msi/server/">
          <file source="SimpleApplicationSetup.msi">
  </files>
.........................
      <includedmanifests>
    <manifest location="msi_patch.xml" manifestid="{C18DC1E6-001C-4d5b-9A84- manifestid="{C18DC1E6-001C-4d5b-9A84-D3E1C580552}"/>
      <manifest location="msi_remove.xml" manifestid="{AAB3F1B4-6CBC-48ea-80FE-5177212BE318}"/>
     </includedmanifests>
    </manifest>
  

Modify the manifestID Attribute for the Update to be Downloaded

The manifestID attribute of the <manifest> element in the manifest file has to be updated for each file that will be downloaded.

Example:

    <manifest mandatory="False" manifestid="{C18DC1E6-001C-4d5b-9A84-DD3E1C580552}"
     xmlns="urn:schemas-microsoft-   com:PAG:updater-application-block:v2:manifest">  
  

Do I Have to Include the Full Path in the Source Attribute of the File Element in Manifest.xml?

No, the full path is not required. The updater will pick up the path from the base attribute of the files element.

Example:

    <files base="http://localhost/Updater2QuickStarts/cs/msi/server/">
     <file source="SimpleApplicationSetup.msi"/>
     </files>  
  

How Should I Change the Manifest.xml File so the Updater Knows There is an Update Available?

You have to change the manifestID attribute of the <manifest> element in the Manifest.xml file on the server. The updater compares the manifest ID of the server's manifest with the applied manifest on the client. The applied manifests are stored in the UAB\applications\<application-id> subfolder, which gets created on the client computer in the application folder.

Example:

    <manifest mandatory="False" manifestid="{C18DC1E6-001C-4d5b-9A84-DD3E1C580552}"
    xmlns="urn:schemas-microsoft-com:PAG:updater-application-block:v2:manifest">     
  

How Do I Provide Partial Updates Using File Hash Comparison?

The Updater Application Block includes the ability to compare file hashes on potential download files to verify whether the versions currently on the client computer differ from the updates available on the server. This lets you minimize the number of downloaded files, therefore minimizing the overall time for the update process to occur.

To do this, perform these steps:

1. Modify the files and file elements in the manifest file.
2. Compare the file hashes of the client and server files.

The next sections describe each step.

Modify the Files and File Elements in the Manifest File

Modify the files and file elements in the manifest file to include the hash comparison flag, the hash of the file on the server, and the hash provider to use.

Example:

    <files base="http://localhost/Updater2QuickStarts/cs/AutoInproc/server/" 
      hashcomparison="Yes" hashprovider="hmac1">
      <file hash="a5aqUnlIyzu670VDJW8lSwXJdJM=" source="AutoInproc.exe">
          <file hash="0UOXi/+fNtBihjD9Vv8WS+1NBCo=" source="AutoInproc.pdb">
     </files> 
  

Compare the File Hashes of the Client and Server Files

When the manifest is retrieved from the server, the hash comparison flag is checked. If this flag is set to true, the hash value retrieved from the manifest is compared with the file on the client computer; if the file has not changed, it is removed from the list of files to download in the manifest class.

Deployment

How Do I Resolve the "Specified cast not valid" Error Message That I Receive when BITSDownloader Runs?

You receive this error message if the version of Background Intelligent Transfer Service (BITS) that you are using is earlier than version 1.5. IBackgroundCopyJob2 is available in BITS version 1.5 and later.

To do this, perform these steps:

1. Check the version of BITS on your computer.
2. If the version of BITS on your computer is earlier than version 1.5, update it.

To check the version of BITS on your computer, check the version of QMgr.dll.

To find the version number of the DLL

1. Locate QMgr.dll in %windir%\System32.
2. Right-click QMgr.dll, and then click Properties.
3. Click the Version tab.
4. Note the version number. Table 1 lists the versions of BITS and their corresponding QMgr.dll file version numbers.

Table 1: Bits Versions and Corresponding QMgr.dll Versions

If the Version of BITS on Your Computer Is Earlier than Version 1.5, Update It

Your computer should have BITS 1.5 or later installed on it. On Microsoft Windows XP, BITS 2.0 gets installed as part of Service Pack 2.

If you need a later version of BITS, download the version you need:

• For version 2.0, see "Update for Background Intelligent Transfer Service (BITS) 2.0 and WinHTTP 5.1" in the Microsoft Download Center at http://www.microsoft.com/downloads/details.aspx?FamilyID=B93356B1-BA43-480F-983D-EB19368F9047&displaylang=en.
• For version 1.5, see "Background Intelligent Transfer Service Version 1.5 (Client Component)" in the Microsoft Download Center at http://www.microsoft.com/downloads/details.aspx?FamilyID=8c6ef6c8-2abf-43c7-ab51-e0c53303086d&DisplayLang=en.

How Do I Resolve the "System.UnauthorizedAccessException" Message That I Receive While Using UAB in My Web Application?

To do this, follow these steps:

1. Confirm that the Manifest.xml file in the Web application has read permissions in IIS.
2. If it does not have read permissions, select the read attribute of the Manifest.xml file.

To check that the Manifest.xml file in the Web application has read permissions in IIS

1. In IIS, right-click the folder that contains the Manifest.xml file, and then click Properties.
2. Click the Directory tab. If it has read permissions, the Read check box is selected.

   If the Read check box is not selected, select it.

How Do I Remove the Earlier Version Folders From the Client Computer?

To do this, follow these steps:

1. Develop the custom activation processor.
2. Configure the custom activation processor.

The next sections describe each of these steps.

Develop the Custom Activation Processor

To create an activation processor class

1. Add references to the following assemblies:
   • Microsoft.ApplicationBlocks.Updater.dll
   • Microsoft.Practices.EnterpriseLibrary.Configuration.dll
2. Import the Microsoft.ApplicationBlocks.Updater namespace.
3. Create a new class, which implements the IActivationProcessor interface of the Microsoft.ApplicationBlocks.Updater namespace.
4. Implement the following methods defined in the IActivationProcessor interface:
   1. Init. Add any initialization code to this method.
   2. PrepareExecution. Add code to this method to verify that any prerequisites for the execution are met. If the prerequisites are not met, you should raise an exception to the calling code.
   3. Execute. Add code to this method to delete the old version folders.
   4. OnError. Add code to this method that should run if a later processor in the chain fails.

Configure the Custom Activation Processor

You can configure a client application to use a custom activation processor by modifying the activation element in the manifest file.

Example:

  <activation> 
  <tasks>
    <task name="DeletedOldVersionsProcessor" type="MyApp.RegistryProcessor, MyApp"/>
  </tasks>
  </activation>  
  

How Do I Resolve the "Server doesn't support Range Header" Message That I Receive During Setup?

This occurs if your update includes a file whose extension is included in the App Mappings under IIS in the virtual folder configuration.

To resolve this, perform these steps:

1. Check the IIS App Mappings of the application's virtual directory
2. Remove the application mappings for certain file extensions, if required.

To check the IIS App Mappings of the application's virtual directory

1. In IIS, right-click the application's virtual directory, and then click Properties.
2. On the Virtual Directory tab, click the Configuration button.
3. In the Application Configuration dialog box, see if application mappings exist for the update file types. If they do exist, remove them.

Why Does IIS 6.0 Block Requests for Some File Types That Are Requested by the Updater?

Earlier versions of IIS include a wildcard character MIME mapping, which permits IIS to serve any file regardless of its extension. IIS 6.0 does not include this wildcard character MIME mapping and does not serve any type of extension that is not defined at the MIMIE Map node in the IIS metabase.

You have to define the MIME type in IIS for the specific file extension.

To define the MIME type in IIS for the specific file extension

1. Open the IIS Microsoft Management Console (MMC), right-click the virtual directory , and then click Properties.
2. On the HTTP Headers page, click MIME Types.
3. Click New.
4. In the Extension box, type required extension for example.pdb.
5. In the MIME type box, type a valid MIME type (for example, binary).
6. Apply the new settings. IIS now serves files with the extension that you added. In this example, IIS now serves files with the extension specified in step 4.

How do I resolve "The client does not have sufficient rights to the requested server object" error message that I receive when I attempt to download the .Config files with Updater? Why does IIS 6.0 block requests for some file types?

Earlier versions of IIS include a wildcard character MIME mapping, which permits IIS to serve any file regardless of its extension. IIS 6.0 does not include this wildcard character MIME mapping and does not serve any type of extension that is not defined at the MIME Map node in the IIS metabase. You must add the .config extension to the list of registered MIME types to ensure that they are not filtered by the server. In addition, IIS does not allow downloading .config files, since they are used by ASP.NET. So you will remove .config from your application settings.

To download .config files from the Web server, you will need to perform the following steps:

• Define the MIME type in IIS for the specific file extension (.config)
• Remove the App Mapping for certain file extensions (if required)

Define the MIME type in IIS for the specific file extension:

1. Open the IIS Microsoft Management Console (MMC), right-click the Virtual Directory, and then click Properties.
2. On the HTTP Headers page, click MIME Types.
3. Click New.
4. In the Extension box, type.config or any required extension.
5. In the MIME type box, type a valid MIME type (for example, text/xml for .config files).
6. Apply the new settings. IIS now serves files with the extension that you added. In this example, IIS now serves files with the extension specified in step 4.

Remove the App Mapping for certain file extensions (if required)

1. Open the properties of Application Virtual Directory
2. Select the Configuration option from the Virtual Directory Tab
3. In the Application Configuration window (Mapping Tab), check whether App Mapping exists for the File Types (.config)
4. If there is an App Mapping corresponding to the File Type (.config), you will need to remove it.

Downloader

How Do I Use IBackgroundCopyJob2 to Send Credential Information to the Server? Are There Any Samples Available?

The BITS 2.0 fix posted on the GotDotNet workspace contains a BitsCredentialWrapper.cpp file that contains the fix for using IBackgroundCopyJob2 for setting the credentials.

For details, see the GotDotNet workspace at http://practices.gotdotnet.com/projects/updater [Content link no longer available, original URL:http://practices.gotdotnet.com/projects/updater]

How Can I Provide the Proxy Server Information to Download the Manifest Information at Run Time?

To do this, perform the following steps:

• Import the System.Net namespace.
• Provide proxy server Information.

After you import the System.Net namespace, you will need to provide proxy server information before calling the CheckForUpdates method.

Example:

    Uri proxyURI = new Uri ("http://webproxy:80"); 
    GlobalProxySelection.Select = new WebProxy (proxyURI);     
  

Processor

How Do I Perform Certain Operations After the WaitForApplicationExit Processor Installs All Files in the Client Application Folder?

To this, follow these steps:

• Subscribe to the ActivationCompleted event of the ApplicationUpdaterManager.
• Handle the ActivationCompleted event.

To subscribe to ActivationCompleted event of ApplicationUpdaterManager

Declare the event using the syntax shown here.

updater.ActivationCompleted +=new ActivationCompletedEventHandler(updater_ActivationCompleted); 
  

To handle the ActivationCompleted event

Handle the event and write the code for the operation you have to perform after the WaitForApplicationExitProcessor installs all files in the client application folder.

Example:

    private void updater_ActivationCompleted(object sender, ActivationCompleteEventArgs e) 
    { 
    // Add your implementation here 
    }