System Preparation (Sysprep) Provider Developer's Guide for Windows 7

  • Article

Note

This content applies to Windows 7. For Windows 8 content, see Windows Deployment with the Windows ADK.

This documentation helps software developers to create System Preparation (Sysprep) providers. Sysprep is the tool used to prepare a Windows® installation for image capture, or to prepare an installation to be shipped to an end user. Sysprep providers enable you to create custom actions that are processed against your application installation.

Sysprep Providers: Background and How They Work

Some applications require hardware-specific or installation-specific information. For example, an application might require specific information about user accounts, hard-drive paths and partitions, or specific licensing information. Sysprep providers enable you to configure your application to add or remove specific information from your application, to support imaging and deployment scenarios.

The Sysprep tool calls to entry points located in various Sysprep providers. These providers are then responsible for configuring Windows features and any applications used to support imaging scenarios. Sysprep providers can also remove hardware-specific or installation-specific information from a Windows feature or application, when run with the /generalize option. For example, you can use this provider to delete any settings files, logs, or any computer-specific settings that must be removed from the installation before you can capture that image to install to other computers.

After the generalize configuration pass is complete, the specialize configuration pass runs. This configuration pass, along with the relevant Sysprep providers, can be used to configure any installation-specific or hardware-specific information that is required by a Windows feature or an application.

Note

For more information about the Sysprep tool, see the Sysprep Technical Reference topics.

Creating and Registering Your Sysprep Provider

To create a Sysprep provider, you must:

  1. Determine which configuration pass (cleanup, generalize, or specialize) you want to run your Sysprep provider in. For more information, see Determining Your Configuration Pass.

  2. Create the appropriate entry point for your Sysprep provider, based on your choice of configuration pass. For more information, see Creating the Sysprep Provider Entry Point.

  3. Register the Sysprep provider for use by the Sysprep tool. For more information, see Registering Your Sysprep Provider.

Choosing the Right Configuration Pass

You can write a Sysprep provider that will run during the cleanup, generalize, or specialize configuration passes of the Sysprep tool. The following list describes the different passes.

  • Cleanup. Choose this configuration pass if you need to make your application usable by any user after a restart, or if your Sysprep provider actions should always be performed. The cleanup pass runs every time that the Sysprep tool runs.

  • Generalize Choose this configuration pass if you need to remove information from your application prior to shutting down and capturing the Windows installation. The generalize configuration pass is the suggested configuration pass to use when creating your Sysprep providers. The generalize configuration pass only runs if you use the sysprep /generalize command, and should only be used in the scenario where you want to transfer your Windows installation to another computer.

  • Specialize. Choose this configuration pass if your Sysprep provider needs to perform actions that will re-initialize your application after the Windows installation has been transferred to a new computer. For example, if you have installed new hardware or if this is the first boot of the computer for a new user.

Important

Be aware that creating a Sysprep provider that runs during the specialize configuration pass can slow down the installation process for each computer on which the provider runs. We recommend that you strongly consider the performance time of your Sysprep provider or use a different pass, if possible.

Configuration Pass Example

During each of the configuration passes, the Sysprep tool calls to the individual provider libraries that are listed in the configuration pass registry key, and then runs the specific functions listed in the registry key for each Sysprep provider.

In the following scenario, an OEM wants to create a customized Windows image that includes applications:

  1. The OEM installs the Windows operating system, adds any applications, and configures the required settings.

  2. The OEM runs the Sysprep tool with the /generalize option, to prepare the image for deployment to multiple computers.

  3. The cleanup configuration pass runs, removing any software-specific information, including miscellaneous settings files, log files, and other data that should not be left on the computer.

  4. The generalize configuration pass runs, removing any hardware, computer, or operating system-specific information.

  5. The OEM shuts down the computer, and then captures the Windows image.

  6. The OEM then deploys the image to multiple computers on the factory floor.

  7. The computers boot and Windows starts the specialize configuration pass, which recreates the computer and operating system-specific information.

Note

For more information about the configuration passes, see the How Configuration Passes Work topic.

Creating the Sysprep Provider Entry Point

When the Sysprep tool calls into your entry point, based on the configuration pass you chose for your provider, the tool expects to find a function that accepts no command-line options and returns a DWORD value that indicates either success or failure. The following example shows a registered entry point that was created for use by the generalize configuration pass.

DWORD YourComponent_Generalize(){  DWORD dwReturn = ERROR_SUCCESS;  ...  // Do something to generalize machine  // and store return code in dwReturn  //  dwReturn = ... ;  return dwReturn;

If the function call returns any other value than ERROR_SUCCESS, the Sysprep tool will abort the remainder of its processes, which will block the whole deployment process. We recommend that you use this as an early check to diagnose errors, instead of waiting until the entire Sysprep cycle completes. For more information about reviewing your log files, see Reviewing Your Log Files.

Registering Your Sysprep Provider

You must register your Sysprep provider so that it can be run by the Sysprep tool during the application-installation or hardware-installation process. To register your provider, you must install a binary (which can be done when your software or hardware is installed) and you must create a registry key in the appropriate location, based on your configuration pass selection, such as:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Setup\SysPrepExternal\<configuration_pass>\<GUID>

Where <configuration_pass> is the name of your selected configuration pass, (Cleanup, Generalize, or Specialize) and the <GUID> is your GUID string, which must be created as a REG_SZ type and have a data value that includes the full path to your DLL followed by a comma and the DLL entry point. For example, my_actions.dll, my_entrypoint_function_name_for_sysprep.

Testing Your Sysprep Provider

The following sections provide guidance about how to test your Sysprep providers.

Before You Begin Testing

Before you begin testing your Sysprep provider, you must verify the following:

  • You are running the Sysprep tool on a computer that is running a clean installation of the operating system. Sysprep will not run on a computer that is running an upgraded operating system.

  • You have not saved your test files in well-known temporary locations; otherwise, the Sysprep tool will remove them from the computer.

  • You have removed the computer from a domain. The Sysprep tool will remove the computer from the domain if it is domain-joined.

  • You have used the <SkipRearm> option in your unattended setup answer file, so that you can run the generalize configuration pass more than three times on the same operating system image. If you do not use this option, you will receive an error in your log file on the fourth attempt. For more information, see the SkipRearm topic in the Windows® Unattended Setup Reference.

  • You have used the <AutoLogon> option in your unattended setup answer file, so that you can automatically log onto the computer after each restart. For more information, see the AutoLogon topic in the Windows® Unattended Setup Reference.

Sysprep Provider Testing Requirements

The following list includes some basic testing requirements, based on the needs of the Sysprep tool and the overall user experience.

  • Verify that your Sysprep provider removes any information that should not remain on the computer after the Sysprep process is completed. For example, if your provider is meant to run during the generalize configuration pass, you must verify that there are no artifacts from the original computer that would cause the new computer to function incorrectly, such as registry key values or other settings.

  • Verify that the Sysprep process completes successfully. Your provider should not cause any errors. If an error is discovered, you must fix the error before continuing. For more information about reviewing your error log files, see Reviewing Your Log Files.

  • Verify that the Sysprep log files are clean and that there are no fatal errors. You must also verify that there are no warnings or other errors included in the Setuperr.log file, which is located in the %SystemDrive%\Windows\System32\Sysprep\Panther directory.

  • Determine and execute your test scenarios, verifying that the Sysprep provider functions as expected in each situation.

Setting Up Your Test Environment and Testing the Sysprep Provider

Because Sysprep has specific requirements for disk partitions and drive letters, we recommend that you use the following steps to configure your test environment.

  1. Perform a clean installation of the Windows 7 operating system.

  2. Browse to the Sysprep.exe tool, located in the %SystemDrive%\Windows\System32\Sysprep directory.

  3. Back up your mounted-devices key to a registry file, by typing Reg export HKLM\System\MountedDevices at the command prompt.

    Saving this key to a registry file helps you to avoid any potential issues related to drive letter changes.

Note

Because of security concerns, we strongly recommend that you not save this key to any of the common, or well-known, temporary locations.

  1. Run the Sysprep commands, with the /quit option. For example, Sysprep /generalize /oobe /quit, which will instruct Sysprep to generalize the computer (remove the system-specific settings), reboot the computer into OOBE, and then shut down the computer.

  2. Restore your saved mounted devices key, by typing Reg import HKLM\System\MountedDevices at the command prompt.

  3. Boot the computer into the Windows Preinstallation Environment (Windows PE).

  4. Using an image-capturing program, such as ImageX, to capture your image and store it on either a network share or on removable media.

  5. Boot at least three different computers, each with different hardware, into Windows PE.

  6. Apply the image to each of the three computers, reboot the computers, complete the OOBE process to get to the desktop, and verify that your application works properly.

Testing Tips

This section provides a couple of tips for testing your Sysprep provider.

  • Complete the entire Sysprep process, including restarting the computer. You will receive error messages in your log files if you restart the Sysprep process without first restarting the computer.

  • Do not automatically restart the Sysprep process after errors occur, because the operating system image has become unusable. Instead, review the log files to determine the root cause of the issue, and then reinstall the operating system for further Sysprep tests.

Reviewing Your Log Files

The Sysprep tool writes to the setupact.log file, located in the %windir%\System32\Sysprep\Panther directory, during both the generalize and cleanup configuration passes. In addition, any error message marked with the LOG_ERROR severity is written to both the setupact.log file and to the setuperr.log file, which appears in the same directory. The Sysprep tool will never overwrite or delete the setupact.log file, it will only append data to the end.

During the specialize configuration pass, Windows Setup initializes the Panther log file engine, and then calls to the Sysprep library code; therefore, any error messages that occur during this configuration pass will appear in the main Windows Setup log file, setupact.log file, which is located in the %windir%\Panther\ directory. This log file is overwritten when a new specialize configuration pass runs.

Additional Resources

For more detailed information about the configuration passes, unattended-Setup settings, the Setup process, or how to add applications, we recommend that you review the following: