Windows PE Developer’s Guide 4
WindowsPE Developer’s Guide
Microsoft Corporation
April, 2007
Applies to:
WindowsPE 2.0
Summary: Provides information about the Windows Preinstallation Environment (WindowsPE) for the Microsoft® Windows® family of operating systems. It provides guidelines for independent software vendors (ISVs) and original equipment manufacturers (OEMs) to develop and to debug deployment, diagnostics, and recovery applications that run in WindowsPE.
©2007MicrosoftCorporation. All rights reserved.
Windows PE Developer’s Guide 4
Disclaimer
The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.
This white paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, AS TO THE INFORMATION IN THIS DOCUMENT.
Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.
Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.
Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place or event is intended or should be inferred.
© 2007 Microsoft Corporation. All rights reserved.
Microsoft, Win32, Windows, and WindowsNT are either registered trademarks or trademarks of Microsoft Corporation in the United States or other countries or regions.
The names of actual companies and products mentioned herein may be the trademarks of their respective owners.
©2007MicrosoftCorporation. All rights reserved.
Windows PE Developer’s Guide 4
Contents
Introduction 1
Building WindowsPE Applications 2
Development Platforms and Tools 2
Runtime Environment 2
Project Build Settings 3
Creating a Windows PE Image and Adding Applications 3
Debugging Applications in WindowsPE 8
Programming for WindowsPE 9
Design Considerations 9
Statelessness 9
RAMDISK Boot 9
File-based Write Filter (“Scratch Space”) 10
Usage of Microsoft Virtual PC 10
Extensibility Points 10
Winpeshl.exe 11
Wpeinit.exe / Wpeutil.exe / Wpeutil.dll 11
Desktop Settings 13
References 13
WindowsPE API Compatibility Reference 13
Overview 13
Supported APIs 13
Unsupported APIs 14
Windows Subsystems Reference 14
WindowsPE Documentation 15
Glossary 16
©2007MicrosoftCorporation. All rights reserved.
WindowsPE Developer’s Guide 7
Introduction
The Windows® Preinstallation Environment (WindowsPE) is the core technology for the diagnostics, deployment, and recovery of Microsoft® Windows operating systems. It is a bootable collection of Windows components that will run from a variety of media without installation.
WindowsPE is licensed to independent software vendors (ISVs) and original equipment manufacturers (OEMs) for the purposes of creating customized deployment, diagnostics, and recovery utilities. This document outlines the development best practices, capabilities, and limitations of WindowsPE. It is intended for ISVs and OEMs, and it applies to WindowsPE 2.0, which is based on components from the WindowsVista® operating system.
WindowsPE 2.0 comes in both 32-bit x86 and 64-bit x64 versions. The 32-bit version must be used to install, recover, and troubleshoot 32-bit versions of Windows; likewise, the 64-bit version must be used to service 64-bit versions of Windows. The 64-bit version does not support WOW64, so it can execute only 64-bit applications and drivers.
WindowsPE is a bootstrap environment with enough core functionality to enable deployment, diagnostics, and recovery scenarios. It is capable of booting and running without installation or online configuration. It can be booted from the network with PXE, a CD/DVD, a USB Flash Device (UFD), or a hard disk. It also has the ability to run entirely from random access memory (RAM). For a high-level overview of WindowsPE 2.0 that includes a list of new features, go to the WindowsPE 2.0 for WindowsVista Overview (http://go.microsoft.com/fwlink/?LinkId=80812).
Figure 1. A simplified diagram of the composition of WindowsPE.
WindowsPE is not a general-purpose operating system. It may not be used for any purpose other than deployment, diagnostics, and recovery. It may not be used as a thin client or an embedded operating system. There are other Microsoft products, such as Windows® XP Embedded and WindowsCE, which may be used for these purposes.
When creating a product for WindowsPE, you may not add additional Windows code to your product without consent from Microsoft. You may add code that you have created or have licensed for redistribution from a third party. For answers to WindowsPE licensing questions, send e-mail to .
Building WindowsPE Applications
You can develop 32-bit and 64-bit applications and dynamic link libraries (DLLs) for WindowsPE with native C and C++ and the subsystems and application programming interfaces (APIs) listed in the “WindowsPE API Compatibility Reference” later in this document.
WindowsPE uses MFC42.dll, but does not support other versions of MFC. Therefore, applications based on MFC are not supported on Windows PE. Likewise, Windows PE does not support ATL.
WindowsPE does not support the .NET Framework, so you cannot build managed applications or components with C#, Visual Basic, .NET, or managed C++.
Development Platforms and Tools
To build applications for WindowsPE 2.0, you can host the build environment on WindowsVista, WindowsXP, or Windows Server2003. The required build tools for each host are listed in this table.
Host Windows Version / Required Build ToolsWindowsVista / Windows SDK for WindowsVista
Visual Studio .NET 2005 with Service Pack 1 (SP1)
Support Update for WindowsVista
Windows Automated Installation Kit (WindowsAIK)
WindowsXP and Windows Server2003 / Windows SDK for WindowsVista
Visual Studio .NET 2005 or Visual Studio .NET 2003
Windows Automated Installation Kit (WindowsAIK)
The Windows SDK provides information on how to build Win32 applications, including documentation, header files, and libraries. You can obtain the Windows SDK for WindowsVista from the Microsoft Web site at http://go.microsoft.com/fwlink/?LinkID=80852.
The WindowsAIK is required because it contains WindowsPE 2.0 and its offline customization tools.
Microsoft recommends that you install Visual Studio before installing the Windows SDK. Visual Studio enables the SDK installer to set its .include, .lib, and .bin directories to work correctly with Visual Studio. The Windows AIK may be installed before or after Visual Studio and the Windows SDK.
Runtime Environment
WindowsPE requires an ACPI-compliant computer with at least 512megabytes (MB) RAM for RAMDISK operation and 256MB RAM for non-RAMDISK operation. Applications that require significant amounts of RAM may increase this minimum requirement. Be sure to determine the minimum amount of RAM needed for your application plus Windows PE.
Project Build Settings
This section describes some of the basic Visual Studio project settings that may be different from the defaults created by the Visual Studio Project Wizard. Please read this section to ensure that you set up your project’s build settings to produce applications and DLLs that are compatible with Windows PE.
You must develop Windows PE applications with native C or C++ code that does not use MFC or ATL. Therefore, if you use the Visual Studio Project Wizard, choose a Win32 project and make sure that both MFC and ATL are not checked.
Set your project options to link to the static C/C++ runtime libraries, not the .dll version of Msvcrt.dll. Open your project properties and set “Configuration Properties \ C/C++ RunTime Library” to “Multi-threaded” or “Multi-threaded debug,” not one of the .dll versions. If you do not perform this step, then your application might not run on WindowsPE.
NoteYour application can use customized .dll files that you write or license from a third party. Add these .dll files to your application for WindowsPE. However, do not use Msvcrt.dll and do not include additional Windows .dll files that are not part of WindowsPE.
If you plan to host your application on the 64-bit version of WindowsPE, set the project build options to compile all binaries with the x64 compiler in Visual Studio. If you plan to host your application on the 32-bit version of WindowsPE, set the project options to compile with the x86 compiler.
NoteBe sure that your project does not have the /clr: compiler option set. This option produces managed C++ code, which will not run on Windows PE.
Creating a Windows PE Image and Adding Applications
The following steps show how to create a Windows PE image, customize the image to include specific Windows PE features, add your application files to the image, and produce a bootable CD-ROM or USB Flash Drive.
For additional details on how to further customize your Windows PE image, refer to the Windows Preinstallation Environment (Windows PE) User's Guide (Winpe.chm) in the Windows AIK.
Step 1: Set up a WindowsPE Build Environment
In this step, you will create a required directory structure that supports building a WindowsPE image.
1. On your build computer, click Start, point to All Programs, point to WindowsOPK or WindowsAIK, and then click WindowsPE Tools Command Prompt.
The menu shortcut opens a Command Prompt window and automatically sets environment variables to point to all the necessary tools. By default, all tools are installed at C:\Program Files\<version>\Tools, where <version> can be WindowsOPK or WindowsAIK.
2. At the command prompt, run the Copype.cmd script. The script requires two arguments: hardware architecture and destination location where the WindowsPE image will be created. For example,
copype.cmd <arch> <destination>Where <arch> can be x86 or amd64 and <destination> is a path to the local directory. For example,
copype.cmd x86 c:\winpe_x86The script creates the following directory structure and copies all the necessary files for that architecture. For example,
\winpe_x86\winpe_x86\ISO
\winpe_x86\mount
Step 2: Mount the Base WindowsPE Image
In this step, you will mount the base image to a local directory so that you can add or remove packages.
· At the command prompt, mount the base WindowsPE image (Winpe.wim) to the \mount directory by using ImageX. For example,
imagex /mountrw c:\winpe_x86\winpe.wim 1 c:\winpe_x86\mountStep 3: Add Additional Packages
By using the Peimg tool, you will install Windows features by using the /install option. Windows features are included with the base image (Winpe.wim) but are not installed. You can also import packages and add drivers and language packs. For more information, see the Windows Preinstallation Environment (Windows PE) User's Guide (winpe.chm).
1. Add a Windows feature to the base image by using the peimg /install command. For example,
2. Repeat step 1 for each package.
peimg /install=<pkg> c:\winpe_x86\mount\Windowswhere <pkg> denotes the package name. A list of available packages and their names can be obtained by using the /list command. Wildcards can be used when specifying a package name. Any packages with matching names will be installed. For example,
peimg /install=WinPE-HTA-Package c:\winpe_x86\mount\Windows-OR-
peimg /install=*HTA* c:\winpe_x86\mount\Windowswhere wildcards denote any package with HTA in the package name.
WindowsPE 2.0 provides the following Windows features referred to as packages:
Package Name / DescriptionWinPE-FONTSupport-<region>
-Packages / Additional font support for ja-jp, ko-kr, zh-cn, zh-hk,
and zh-tw.
WinPE-HTA-Package / HTML application support
WinPE-MDAC-Package / Microsoft Data Access Component support
WinPE-Scripting-Package / Windows Script Host support
WinPE-SRT-Package / Windows Recovery Environment component
WinPE-WMI-Packages / Windows Management Instrumentation (WMI)
support
WinPE-XML-Package / Microsoft XML (MSXML) parser support
3. Verify that the packages were installed by using the peimg /list command to view all packages in the current image. For example,
peimg /list c:\winpe_x86\mount\WindowsIn the INS column, (+) denotes installed packages and (-) denotes not installed.
Step 4: Add Your Application and Additional Customizations
This step is where you add your application and its support files to your WindowsPE image. You can also add any scripts that you need while WindowsPE is running.
1. Copy your application files into the WindowsPE image. For example, if your application is “myApp.exe”, then type:
copy myApp.exe mount\”Program Files”2. The following is a list of common tools you might want to include in your WindowsPE image:
· ImageX
A command-line tool for capturing and applying images during deployment scenarios. For example, at a command prompt,
copy “c:\program files\<version>\Tools\x86\imagex.exe” c:\winpe_x86\iso\· Package Manager (Pkgmgr.exe)
A tool for servicing Windows image (.wim) files offline. You must copy the entire \Servicing folder and MSXML6 binaries. Offline servicing requires ImageX. For example,
xcopy “c:\program files\<version>\Tools\<architecture>\Servicing” c:\winpe_x86\iso\Servicing /scopy %windir%\system32\msxml6*.dll c:\winpe_x86\iso\Servicing
Where <version> can be WindowsOPK or WindowsAIK and <architecture> can be x86, amd64, or ia64. In both previous examples, the tools are not loaded into memory during a WindowsPE RAM boot. The media must be available to access the tools.
To load the tools into memory along with WindowsPE, copy the source files into the mounted \Windows directory. For example,
c:\winpe_x86\mount\WindowsImportantAdding files to the \Windows directory will increase the size of your WindowsPE RAM image. Make sure your computer has sufficient memory to boot WindowsPE and run various applications.
Step 5: Prepare the Image
In this step, you will prepare the image by using the peimg /prep command. This operation removes any non-installed packages from the final image. This operation reduces the overall image size. For example,
peimg /prep c:\winpe_x86\mount\WindowsThe /prep option cannot be reverted, and after the /prep option is run, the /install, /uninstall, /import, and /list options will not function, while the /lang and /inf options will continue to function. The Peimg tool prompts you to confirm the command. To suppress this prompt for scripting, add the /f option.
Step 6: Commit Changes to the Image
In this step, you commit the changes to the original image file (Winpe.wim) by using the ImageX /unmount option with the /commit option. For example,