OFF97: Contents of Relnotes.doc for the NIW

• Microsoft Network Installation Wizard, version 2.0
• Microsoft Office 97 for Windows

SUMMARY

This article contains the contents of the Relnotes.doc file that comes with the Microsoft Network Installation Wizard (NIW), version 2.0.

MORE INFORMATION

The self-extracting file, Setupniw.exe, in the Tools\NIW folder on the "Office Resource Kit" Tools and Utilities compact disc for Office 97, contains Relnotes.doc. This document is installed when you double-click Setupniw.exe.

To access the NIW online, connect to the following Web site:

   http://www.microsoft.com/office/ork/

   http://www.microsoft.com/

CONTENTS OF THE NETWORK INSTALLATION WIZARD RELEASE NOTES FILE

Section 1

Introduction

Understand the motivation behind the 2.0 version of the network Installation Wizard.

The 1.0 version of the Network Installation Wizard (NIW) was introduced with the original version of the Office Resource Kit for Office 95. Its goals included helping to lower the threshold for rolling out Office in a corporate environment by facilitating the creation of custom installation scripts. Given the feedback we've received since Office 95 made its debut, NIW 1.0 has been a success. However, from an implementation and support perspective we soon discovered our burden for NIW 1.0 was quite high. So the primary motivation for embarking on a new version of NIW was to reduce this burden.

In addition to reducing our support burden, we also had the advantage of feedback from corporate sites on how they use the 1.0 version of NIW and how they would like to use it. Combining a reduced support burden with corporate feedback and new functionality in our installation tools for Office 97 we came up with a short list of requirements for the 2.0 version. The list includes:

• Performance Improvements
• Generalization
• Wizard User Interface
• New Features

One of the most common complaints about the 1.0 version of NIW was how long it took reading Office's Setup Table File (STF). So, we began the 2.0 effort by profiling the 1.0 version to determine where the bottlenecks were. This effort pointed to a couple of areas for improvement: converting the code base from 16-bit to 32-bit and abandoning ODBC processing of the STF in favor of an in-memory model.

Converting the code base from 16-bit to 32-bit improved the fault tolerance of NIW 2.0 and allowed us to take advantage of newer 32-bit versions of system services. Although we did not gain a significant performance improvement solely from the port to 32-bit, the gain in stability and marginal performance increase were worth this effort.

In the 1.0 version of NIW the STF was read into a temporary Microsoft Access database first, then processing was carried out through ODBC calls with the resulting records being processed using string manipulation routines. Our profiling determined the ODBC calls were a bottleneck as well as the string manipulation routines we were using. So this approach was abandoned. Instead, a support module (i.e., STFTOOL.DLL) was created which utilized an in memory model for the STF so that fetching records and processing fields within those records could all be done in memory. An enormous performance advantage was gained as a result of this modification. For our reference machine of a 486/33 with 8 Mb of RAM, we cut the time required to read Microsoft Office 95 Professional's STF from 26 minutes to 33 seconds.

Generalization

Part of the reason our support burden for the 1.0 version of NIW was so high was due to its many dependencies on the specific form of Office 95 Professional's STF. Although coding NIW 1.0 to specifics of an STF provided the ability to customize settings specific to Microsoft Office, nearly every change to the STF broke NIW. 1.0 This became painfully evident for the Microsoft Office 95 Standard release as well as each of the upgrades. Plus, the 1.0 version of NIW was unable to customize foreign language versions of Microsoft Office.

As a result, one of the criteria for the 2.0 version was to generalize the code so that it could be backwards compatible to Microsoft Office 95 STFs as well as forward compatible. The cost to administrators, however, is the loss of customizations specific to Microsoft Office like the ability to minimize the Fast Find footprint. But we feel the benefit of being able to customize a variety of STFs outweighs the loss of a few specific Microsoft Office customizations.

Wizard User Interface

In version 1.0 of NIW, the flow through the user interface was rather circuitous. Several instances of returning to the same dialog to choose another path existed. To remedy this, and to cast the user interface into a form made familiar by Windows 95 and now Windows NT 4.0, we flattened out the flow into a wizard. One of the obvious benefits is that a administrator can revisit any of the dialogs in the wizard as many times as they want before actually committing their customizations to file. In addition, flattening out the flow simplifies the interface considerably.

New Features

New functionality in the Windows 95 and in our installation technology has provided two opportunities for enhancements in the 2.0 version of NIW: the Personal special folder in the operating system and installation logs.

Documents Folder

Special folders are a collection of registry entries endowed with unique properties that are used to maintain user profiles. One of these unique properties is the ability to move the folder anywhere and the system continues to track it. Examples of special folders include Desktop, NetHood, Recent, SendTo, and Start Menu.

In Microsoft Office 95, we decided to use one of these special folders, specifically the Personal folder, to implement a single location where all Microsoft Office applications open and save to by default. Doing so would save end users all kinds of grief surrounding organizing and locating data. We named this folder "C:\My Documents." While the reasoning for this feature was sound, we neglected to provide an easy way for corporations to change this location. So the 2.0 version of NIW fills this hole.

While running NIW 2.0, you have the opportunity to set the documents folder for all end users installing using your customized STF. However, there is a caveat. If the Personal special folder has already been defined on an end user's machine prior to installing using your customized STF, your changes will not apply. In other words, the value of the Personal special folder registry value is preserved.

Installation Log

Built into the version of our installation logic used to install Office 97 is the ability to create a post administration install log. This log is a tab delimited text file whose name and location you specify and which gets written to each time an end user performs a post administration operation. Each record in this log file contains the following fields:

   Field          Description
   ------------------------------------------------------------------------

   Date           Date the operation was performed in the form: YYYY-MM-DD.

   Time           Time the operation was performed in the form: HH:MM:SS.

   User           User name of the logged in user at the time the operation
                  was performed.

   Machine        Name of the machine onto which the operation was
                  performed.

   Application    Name of the application being installed, taken from the
                  AppName field in the header section of the STF.

   Version        Version of the product being installed, taken from the
                  AppVersion field in the header section of the STF.

   Operation      Operation being performed (e.g., Install, Remove All)

Section 2

Compatibility

The 2.0 version of NIW can work with other versions of Office's STF as well as other product's STFs altogether.

One of the requirements for the 2.0 version of NIW was to reduce the support burden, which maps directly to generalizing its behavior. Consequently, the 2.0 version provides a quantum leap in compatibility over the 1.0 version. Not only will the 2.0 version of NIW allow you to customize the Microsoft Office 97 Professional STF, but also the various flavors of Microsoft Office 95 (i.e., Professional, Standard, "a" and "b" releases, etc.) Plus going forward, the 2.0 version will work with other Microsoft Office 97 versions like Standard and any bundles or upgrade releases we might make.

Although there are no plans to localize the 2.0 version of NIW itself, it is capable of customizing foreign language STFs as long as they are single byte character languages. Results with double byte character languages are unpredictable and are therefore not recommended.

Section 3

Program Manager Items Versus Shortcuts

What is the difference between the Program Manager Items dialog and the Shortcuts dialog?.

One possible source of confusion involves the difference between the Program Manager Items dialog and the Shortcuts dialog. Both dialogs must be present for backwards compatibility since Microsoft Office 97 can be installed on Windows 95, Windows NT 3.51 and Windows NT 4.0. But the difference between data on the two dialogs is rooted in how STFs are authored.

Before the Windows 95 shell existed there was only the Program Manager. Creating icons in the Program Manager was accomplished by using an install action called AddProgmanItem. This action used DDE to send the necessary commands to Program Manager to create the desired icon in the desired window. An additional flavor of the action also existed and is called AddProgmanItemQuiet, the only difference being the absence of a dialog to allow end users the ability to change the Program Manager window into which the icon is to be created. Both of these actions continue to exist today.

When authoring an installation for Windows NT 3.51, the AddProgmanItem action is used. However, when authoring an installation for Windows 95 or Windows NT 4.0 this action cannot always be used because of the inability of AddProgmanItem to create icons directly on the Start menu, or even on the Programs menu below the Start menu. Instead, a different action called InstallShortcut must be used to create shortcuts in these folders. So, to support products that install on a Windows 3.x style interface as well as a Windows 95 style interface, the 2.0 version of NIW provides dialogs for handling both.

Program Manager Items Dialog

The Program Manager Items dialog contains all AddProgmanItem and AddProgmanItemQuiet actions in the STF, regardless of whether Typical, Custom, or Run from Network Server was chosen on the Installation Type dialog. By default, all of the Program Manager items are checked indicating they will be installed. If there are no AddProgmanItem or AddProgmanItemQuiet actions in the STF, the dialog is skipped.

The advantage of showing all such actions regardless of the installation type is to avoid requiring that administrators visit each installation type explicitly. Instead, decisions can be made for all possible paths by visiting the Program Manager Items dialog only once.

Shortcuts Dialog

The Shortcuts dialog, in turn, contains all InstallShortcut actions in the STF, regardless of whether Typical, Custom, or Run from Network Server was chosen on the Installation Type dialog. The same rules govern this dialog as govern the Program Manager Items dialog, namely: all of the shortcuts are checked on for installation by default and if there are no InstallShortcut actions in the STF the dialog is skipped.

Section 4

Shortcuts

While NIW 2.0 supports organizing the shortcuts that are created on end users' machines, there are some limitations.

Shortcuts on or below the Start menu are difficult to author in the STF because the location of these folders changes per user. Finding the correct folder location depends on a custom action which retrieves the location from the registry. Then the InstallShortcut action depends on the result of the custom action to determine where to place the shortcut. For this reason, as well as some of the subtle order dependencies among lines in an STF, adding new folders to the list of possible folders into which shortcuts can be installed is not supported. However, whether or not shortcuts get installed can be changed and where shortcuts get installed can be changed among the available folders.

Installing/Not Installing Shortcuts

The Shortcuts dialog contains all InstallShortcut actions in the STF, regardless of whether Typical, Custom, or Run from Network Server was chosen on the Installation Type dialog. By default, all of the shortcuts are checked indicating they will be installed. To remove a shortcut from being installed, simply uncheck the shortcut form the list.

Changing Shortcut Folder

As indicated earlier, shortcuts created on the Start menu or any of its sub- menus require an InstallShortcut action that references a different custom action, which returns the location of the folder for the menu. Naturally, more than one InstallShortcut action might reference a single custom action because they are being installed into the same location. The way the location of an installed shortcut is changed, however, is by changing the folder for which the custom action is looking. Therefore, if one of the shortcuts being installed into, say, the Programs menu under Start is changed to the Start menu itself, then all shortcuts that were being installed to the Programs menu get moved to the Start menu. And the reason they all get moved is because the custom action they all reference got changed from Programs to Start menu. Keep in mind, however, there is no easy way to tell in the Shortcuts dialog which shortcuts reference the same custom action and which do not without actually moving shortcuts.

Section 5

Duplicate Items

Several dialogs in NIW 2.0 contain duplicate entries that differ only in their ObjID. What is an ObjID and why do these duplicates occur?.

An STF contains a header section followed by a collection of rows, each row uniquely identified by its object identifier, or ObjID. These ObjIDs are used to determine order as well as for specifying rows anywhere that rows need to be referenced.

Since ObjIDs are unique, they are being used on several NIW 2.0 dialogs to help in identifying duplicate items. The dialogs in question are the Yes/No Questions, Program Manager Items, and Shortcuts dialogs. Duplicate items appear in these dialogs for two reasons:

Install time branching logic in the STF cannot be resolved at the time NIW 2.0 is running

The install mode tree is not built when populating these dialogs.

Branching Logic

Throughout an STF are branches in the installation logic that get evaluated at install time, depending on conditions arising on a particular end user's machine. Since the machine upon which NIW 2.0 is running does not necessarily reflect end user machines, we must present both sides of these logic branches. Customizations must be made for both branches to cover all possible end users installing from the modified STF.

Install Modes

When an end user performs a standalone install of Microsoft Office, one of several options can be chosen. These options typically include Typical, Compact, Custom, and Run From CD. Each of these choices represents a possible install mode and, consequently, a different path through the STF. When populating the Yes/No Questions, Program Manager Items, and Shortcuts dialogs, NIW 2.0 ignores these different install mode paths. Instead, the entire STF is processed from beginning to end. As a result, duplicate items are likely to appear in these dialogs because they reside in different install paths. To help administrators differentiate between duplicate items an ObjID column is provided. Generally speaking, you need to apply customizations to all items appearing in these dialogs to cover all possible circumstances. However, with enough familiarity of the STF format, these ObjIDs can be used to understand exactly the differences between items in these three dialogs.

Section 6

Orphaned Lines

Some products' STFs contain orphaned lines, lines that never get called. Why do these exist and how do they affect NIW 2.0?.

Another possible source of confusion is the existence of orphaned lines in a product's STF. Though uncommon, the possibility does exist for orphaned lines to exist in an STF because the risk of removing them late in a product cycle outweighs any benefit gained by removing them. The three dialogs that are populated by processing the entire STF, rather than following a particular install mode path, display orphaned lines. The affected dialogs are Yes/No Questions, Program Manager Items, and Shortcuts.

There is no adverse affect to customizing orphaned lines from an installation perspective since they never get executed. However, they are a nuisance for administrators since they represent additional customizations that won't really affect end users. But since there is no easy way for an administrator using NIW 2.0 to determine which items in these dialogs are orphaned, they must be treated as if they are valid entries. The only time any confusion would occur is if an administrator expected to see some behavior change they made in NIW 2.0 and didn't, the problem might be an orphaned line.

Section 7

Long and Short Filenames

Either long or short file names are shown on NIW 2.0's main dialogs, never both. How does this affect what gets written to the STF?

By default, NIW 2.0 displays paths and file names in long file name format under the assumption that most administrators and their users are running a long file name capable operating system. In situations where assuming long file name support is invalid, administrators can change what NIW 2.0 displays using the "Return long folder name to previous dialog" check box. Regardless of what is displayed, however, NIW 2.0 always writes both long and short file names to the STF when necessary.

Changing Paths Directly

Several dialogs in NIW 2.0 present locations of folders and allow administrators to change them. The list of dialogs includes:

• Primary Location
• Documents Folder
• Components
• Program Manager Items
• Add Files

Using the Browse Dialog

NIW 2.0 typically runs on an administrator's machine which may or may not be configured the same as an end user machine. Despite this fact, the Browse dialog provides additional benefit in the following ways:

• If the exact location is not known, browsing allows administrators to determine the location without leaving NIW 2.0.
• Specifying the location of folders using the Browse dialog guarantees well formed paths.
• Folder locations can be specified relative to special path properties using the Browse dialog.

Known Issues

Following is a list of known issues with the 2.0 version of the Network Installation Wizard.

No product is perfect when it ships. In fact, retail software products would never ship if perfection were a requirement. Instead, software products are shipped when the benefit of shipping outweighs the risk of any remaining known issues. Below is a list of such known low risk issues. If you find additional issues that do not appear on the list below, please take the time to notify Microsoft so that your issues can get addressed in subsequent versions.

Running Batch Mode Installations

Customizing an installation using NIW 2.0, then performing the installation interactively, may not behave as expected. NIW 2.0 operates on the Batch mode column in an STF which is processed when the /b command line parameter is used with SETUP.EXE. Running an installation interactively processes which ever path is chosen on the AppMainDlg (e.g., Typical, Compact, Complete, Run From Network).

No Field in the STF May Exceed 255 Chars

Although NIW 2.0 offers data validation in some places, for the most part administrators are free to enter data that can cause SETUP.EXE to behave poorly. Always save a back up copy of the STF before modifying it with NIW 2.0, and be careful when entering data directly into any NIW 2.0 fields.

Collapsing Sub-tree On Components Dialog Fails To Update Description

When expanding and collapsing component sub-trees on the Components dialog it is occasionally possible to get the description out of sync with the currently selected component. Simply selecting a component in the tree pane will properly reset the description.

No Leading "\" When Adding Registry Keys

When specifying a registry key on the Add Registry Entry dialog, do not precede the name of the key with a backslash ("\"). For example, specifying the CurrentVersion key in the registry is accomplished using the following syntax:

   Software\Microsoft\Windows\CurrentVersion

No Validation That Registry Value Data and Data Type Are In Sync

To add a registry entry in NIW 2.0 an administrator must provide the registry root, the data type for the value, the key, the value name, the actual data for the value, and an optional description. The data type for the value data is chosen from a combo box. NIW 2.0 makes no attempt to verify that the value data an administrator enters is of the same data type as indicated in the data type combo box. If value data and its data type clash, the problem will not present itself until a user attempts to install using the customized STF or when the application being installed is actually run.

State Of "Return long folder name to previous dialog" Check Box Affects All Dialogs

Changing the state of this check box on the Browse dialog determines whether to display paths using long or short file name syntax for all dialogs in NIW 2.0.

Up/Down Arrows Toggle Check Boxes

Several NIW 2.0 dialogs contain lists of items that can be checked or not. In some cases, scrolling through items in these lists using the up and down arrow keys can cause check boxes to change their state from checked to unchecked, or vise versa.

Working Folder Field Sometimes Blank, Sometimes <NoneSpecified>

Several of the dialogs in NIW 2.0 contain a working folder field. There is an implicit assumption made that when the working folder field is blank in the STF, the working folder is either optional or is inherited from its parent. Either way, NIW 2.0 does not always handle empty working folders consistently: some are actually blank and some contain a property called <NoneSpecified>. Both are equivalent.

Only Admin. STFs Are Supported

NIW 2.0 can be used to open and modify a floppy mode STF, but using NIW 2.0 in this manner has not been tested nor is it supported.

Progress Indicator Goes To Extreme Upper Left Corner On NT 3.51

In some situations on Windows NT 3.51, the progress indicator is displayed in the upper left corner of the screen. Functionality is not affected by this peculiarity.

Working Directory On Shortcuts Dialog

Working directories are typically not provided when authoring the InstallShortcut action. The reason for this is simple: shortcuts without a working directory have an assumed working directory - the directory in which the shortcut file (i.e., *.LNK) resides. Therefore, reading a long and short name version of a working directory from the STF is not possible. So, when specifying a working directory for a shortcut that is different from the default, you should use the Browse dialog along with the "Return long folder name to previous dialog" check box. Only one working directory is entered, long or short, depending upon the state of the check box. To enter a long name formatted working directory, enter it in the Long name field and make certain the check box is checked. For a short name formatted working directory, enter it into the Short name field and uncheck the check box.

REFERENCES

"Microsoft Office 97 Resource Kit," Chapter 6, "Customizing Client Installations"