Using the Windows Deployment Services Client API

In environments where a standard Windows Deployment Services (WDS) solution cannot be used to install Windows, the API of the WDS client enables developers to write custom deployment applications. Applications can use this API to communicate with the WDS server to get information about system images available from the server. Custom WDS client applications should adhere to the following guidelines.

Install the WDS Role on the Server

  • Windows Deployment Services (WDS) is the revised version of Remote Installation Services (RIS), you will need the WDS server role on the server to implement custom WDS client solutions.
  • WDS replaces RIS as the standard component starting with Windows Server 2008 and Windows Server 2003 with Service Pack 2 (SP2).
  • You must update the RIS server to WDS on Windows Server 2003 with Service Pack 1 (SP1). You can install the WDS server role with the Windows Automated Installation Kit (WAIK).

Start Windows PE 2.0

Windows PE 2.0 must be started, if not already started. The WDS client and supporting DLLs are only loaded by setup.exe when it is in the Microsoft Windows Preinstallation Environment (Windows PE 2.0) phase of setup processing.

  • When a new computer is connected to the network, the built-in preboot execution environment (PXE) technology can be used to download the Network Boot Program. For more information about PXE-booting a computer to install Windows, see The Windows Deployment Services Update Step-by-Step Guide.
  • A RAMDISK bootable image of Windows PE 2.0 can be stored in the .WIM format and downloaded as part of the network boot process. Windows PE can then be loaded and run directly from that media.

Open a session with the WDS server

The WDS client must open a session with a WDS server.

  • Use the WdsCliCreateSession function to open a session with a WDS server. This function takes the name or IP address of the server and receives the address of the handle for the WDS client session.
  • If opening the session with the server will require authenticating the WDS client, the application should provide the address of a WDS_CLI_CRED structure containing the client credentials when calling the WdsCliCreateSession function. The application can use the WdsCliAuthorizeSession function to convert an anonymous session into an authenticated session.
  • When the session opened with the WdsCliCreateSession function is no longer needed, the application should use the WdsCliClose function to close the handle and release resources held by the session.

Enumerate system images on the WDS server

The WDS client can use the API to enumerate the system images on the WDS server.

Get information about images

The WDS client can use the API to get information about the images on a WDS server. The following functions get information about the current image. Because the WdsCliFindFirstImage and WdsCliFindNextImage functions change the current image handle value, the application should store any information it gets and will need in the future before calling the WdsCliFindFirstImage or WdsCliFindNextImage functions again.

Log WDS Client Events

The logging functionality of the WDS client library enables installation progress events to be sent from the client to the WDS server.

  • Use the WdsCliInitializeLog function to initialize the log for the WDS client session.
  • Use the WdsCliLog function to write event messages to the WDS server log.
  • On Windows Server 2008, the WDS server writes client events to an application specific event log that is viewable through eventvwr.exe as well as the debug trace log. On Windows Server 2003 with debug logging enabled, the WDS server will write client events to the log file located at %windir%\tracing\wdsserver.log. WDS Client logging must be enabled on the server to capture these events.

Related topics

About the Windows Deployment Services API
Using the Windows Deployment Services Server API



Community Additions