DUAScriptGen User's Guide

  • Article

Introduction

DUAScriptGen is a standalone tool designed to simplify the process of creating a DUA script file that can be used to deploy software updates to Windows XP Embedded devices. Most settings that are supported by the DUA script compiler can be automatically generated using DUAScriptGen, which helps avoid syntax errors and speeds up the process of creating and deploying updates to devices in the field.

Setup and System Requirements

DUAScriptGen is a C# application. There is not a setup program for DUAScriptGen. All of the files are contained within a zip file that can be extracted and run on a computer that has the .NET Framework 2.0 or higher installed. The latest version of DUAScriptGen can be downloaded from the Releases tab of the Codeplex project site at https://www.codeplex.com/duascriptgen.

All system requirements of the .NET Framework 2.0 apply to DUAScriptGen as well.

In order to utilize the compiler functionality of DUAScriptGen, the Windows Embedded tools must also be installed on the computer that DUAScriptGen is run on.

DUAScriptGen Global Settings

When DUAScriptGen is run for the first time on a computer, it displays a dialog with configuration settings that are required in order to generate a DUA script file. The settings can be changed at any time after first launch by going to the Tool menu and choosing Options. These settings are stored in the HKEY_CURRENT_USER registry hive, so they are specific to each user account on the computer.

DUA polling can be configured to search an HTTP location or a directory. The polling option set in the DUAScriptGen settings dialog controls whether or not the resulting script will contain HTTPGET commands or file move/copy commands. If the user chooses to poll an HTTP location, the user should specify the name of the server that will be used to host DUA script files along with an optional relative path on the server. If the user chooses to poll a share location, the user can specify a UNC path (\\machine\share for example) or a local folder.

The local DUA folder is the working directory that the Device Update Agent service uses as an intermediate location to download files to before copying, moving or executing them. This should be set to the same local folder that DUA was configured to use when building the Windows XP Embedded image.

The next DUA script is an optional field that allows the user to specify the name of a new DUA script to search for when DUA is done processing the current script. If this value is set, DUAScriptGen will update the registry location that tells the DUA service what script file to search for.

The reboot check box allows the user to specify whether or not they want the DUA service to reboot the Windows XP Embedded device after applying the changes specified in the script. DUAScriptGen will write the appropriate command to the end of the script if this check box is checked.

File Operations

DUAScriptGen can generate entries for the following file operations:

  • Copy
  • Copy and execute
  • Delete
  • Execute
  • Move
  • Move and execute

Files can be added by clicking the Add File(s) button in the DUAScriptGen UI, by dragging and dropping one or more files directly onto the file list view or by importing a Windows XP Embedded QFE (described below). Once a file is added, the details about the file can be modified by double-clicking on the file in the list view or by highlighting the file to be changed and clicking the Edit File button.

The DUAScriptGen Edit File dialog allows the user to specify the destination folder for a file. It contains a list of well-known folders that are used by the Windows XP Embedded operating system, and also allows the user to specify any other folder and also indicate whether or not the folder should be created first.

Other values that can be changed in the DUAScriptGen Edit File dialog include the operation to perform on the file, the command line parameters to pass to the file if one of the operations is chosen that includes executing the file and whether or not the file could be in use on the Windows XP Embedded system and should therefore be renamed and removed after a reboot as described at https://msdn.microsoft.com/library/default.asp?url=/library/en-us/xpehelp/html/xeoriupdatingsystemfilesusingdeviceupdateagent.asp.

Files can be removed from the list view by selecting one or more files (hold down CTRL and click in order to highlight multiple files) and then clicking the Remove File(s) button. In addition, the entire list of files can be cleared by going to the File menu and choosing Clear all files.

Registry Entry Operations

DUAScriptGen can generate entries for the following registry operations:

  • Create key
  • Create key and add value
  • Delete key
  • Delete value

Save key and restore key functionality has not yet been implemented in the current version of DUAScriptGen.

Individual registry entries can be added by clicking the Add Key button in the DUAScriptGen UI. Multiple registry entries can be added by dragging and dropping a valid registry file (a .reg file that can be created by exporting keys and/or values using regedit.exe) directly onto the file list view, by clicking the Import Key(s) button or by importing a Windows XP Embedded QFE (described below). Once a registry entry is added, the details about the registry entry can be modified by double-clicking on the item in the list view or by highlighting the item to be changed and clicking the Edit Key button.

The DUAScriptGen Edit Registry Data Item dialog allows the user to update all of the following properties of the registry entry:

  • Operation to perform for this registry entry
  • Registry root name
  • Registry key name
  • Registry value name
  • Registry value data
  • Registry value data type

Registry entries can be removed from the list view by selecting one or more items (hold down CTRL and click in order to highlight multiple items) and then clicking the Remove Key(s) button. In addition, the entire list of registry entries can be cleared by going to the File menu and choosing Clear all registry.

Note: DUA expects to receive registry values that contain binary data in decimal format rather than hexadecimal format. When importing a registry file, DUAScriptGen converts these values from hexadecimal to decimal format automatically. When entering a new binary registry value manually in the DUAScriptGen UI, make sure to convert the hexadecimal values to decimal values manually beforehand.

Creating and Compiling DUA Script Files

Once all of the desired file and registry entries have been created or imported into the DUAScriptGen UI, click the Generate Script button or choose Generate script from the File menu to create a DUA script (DUS) file. You will be prompted to provide a location to save the DUS file, and you must have write permission to the location that you choose.

To compile a DUA script file, you must first create and save a DUA script file in DUAScriptGen or load a previously saved DUA script file (described below). Clicking the Execute Compiler button or choosing the Execute compiler option in the File menu will launch the DUA script compiler (dusc.exe) on the most recently created/loaded DUS file if Windows Embedded Studio is installed on the machine. DUAScriptGen will create the compiled DUA script (DUP) file in a sub-directory named DUA_Files in the same location as the DUS file, and the file will be named the same as the DUS file except for the file extension.

Converting Windows XP Embedded QFE Files

DUAScriptGen supports importing a full list of files and registry keys from a Windows XP Embedded QFE and then generating a DUA script file for the QFE. This feature requires a QFE release note file in RTF format. Release note files can be downloaded from the same location as the QFE packages themselves. See https://msdn.microsoft.com/embedded/downloads/xp/default.aspx for more information about downloaded Windows XP Embedded QFEs.

To import the contents of a QFE release notes file, click the Convert QFE to DUA button and browse to the name of the release note RTF file, then click Open. The information about all files and registry entries contained in the QFE will be populated into the DUAScriptGen UI. After making any desired changes, click the Generate Script button to create a DUA script file and Execute Compiler to compile it into a valid DUA script binary (DUP) file.

Note: QFE release notes list registry values that contain binary data in hexadecimal format, but DUA expects these values to be in decimal format. DUAScriptGen converts these values from hexadecimal to decimal format automatically when importing a QFE file. As a result, you will see the decimal value in the DUAScriptGen UI, which will be different than the value listed in the QFE release notes file.

Converting Windows Hotfix INF Files

DUAScriptGen supports importing a full list of files and registry keys from a Windows hotfix package and then generating a DUA script file that represents the changes described by the hotfix package. This feature requires a hotfix update.inf file. Windows hotfixes can be downloaded from the Microsoft Download Center, and then extracted by running <name of hotfix package> /x:<folder path>.

To import the contents of a hotfix INF file, click the Convert INF to DUA button and browse to the name of the INF file from an expanded Windows hotfix, then click Open. The information about all files and registry entries contained in the INF will be populated into the DUAScriptGen UI. After making any desired changes, click the Generate Script button to create a DUA script file and Execute Compiler to compile it into a valid DUA script binary (DUP) file.

Note: Windows hotfix INF files contain tokens that represent folders where files are intended to be installed. Some of these tokens change from hotfix to hotfix and DUAScriptGen may not understand a particular folder token. If DUAScriptGen does not recognize a folder token, it will skip processing the file(s) that are installed to that folder. It is strongly advised that you inspect the contents of your DUS file and test deploying the hotfix via DUA before rolling out the hotfix to devices in the field.

Silent Mode and Command Line Switches

DUAScriptGen supports parsing release notes files and Windows hotfix INF files and generating DUS files in silent mode for users who want to script DUS file creation instead of interacting with the UI. To use this feature you need to run DUAScriptGen.exe with the following command line parameters:

  • /i <full path to input RTF, HTM or INF file>
  • /o <full path to output DUS file>

For example, you can run the following to parse c:\dua\update.inf and create c:\dua\update.dus:

DUAScriptGen.exe /i c:\dua\update.inf /o c:\dua\update.dus

Additional Features

DUAScriptGen allows the user to load and edit a DUA script file that was previously created by DUAScriptGen. Go to the File menu and choose Load DUS file, and then browse to the location of the DUA script file and click Open to load it into the DUAScriptGen UI.

Support Information

The DUAScriptGen tool was originally written by Mike Hall and Aaron Stebner and has been published via Codeplex. Support for the tool will be provided via the Codeplex project site:

https://www.codeplex.com/duascriptgen/  

All feedback, suggestions, bug reports and feature requests are welcome and encouraged.