Share via

PackageWriter.AddReplacementDriver Method (string, string, out StringCollection, out StringCollection)

Note

Beginning with the refreshed version of the HLK (updated February 2026), the AddDriver and AddReplacementDriver methods will include a new check for files in the driver package that were not referenced by an .inf file. This information will be available through warningMessages. There will also be new AddDriver and AddReplacementDriver overloads that expose the unreferenced file information through output arguments in addition to warningMessages.

This method replaces a driver for an Update Package and checks the driver files for driver signability. The signability tests are done when drivers are added to the package. If the signability tests fail the driver is not added to the package. Down level OS signability tests are automatically run. Errors from these signability results will not prevent submission creation (will not cause a false return value). The error messages for down level operating system signability runs will be captured and returned as warnings.

This method also checks for unreferenced files, and generates a log listing all unreferenced and referenced files. If the driver package has at least one unreferenced file, a path to the unreferenced file log is appended to warningMessages.

Namespace: Microsoft.Windows.Kits.Hardware.ObjectModel.Submission

Assembly: Microsoft.Windows.Kits.Hardware.ObjectModel.Submission (in Microsoft.Windows.Kits.Hardware.ObjectModel.Submission)

Usage

Visual Basic

Dim instance As PackageWriter

Dim pathToNewDriver As String

Dim replacesDriverId As String

Dim errorMessages As StringCollection

Dim warningMessages As StringCollection

Dim returnValue As Boolean

returnValue = instance.AddReplacementDriver(pathToNewDriver, replacesDriverId, errorMessages, warningMessages)

Syntax

Visual Basic

Public Function AddReplacementDriver ( _

          pathToNewDriver As String, _

          replacesDriverId As String, _

          <OutAttribute> ByRef errorMessages As StringCollection, _

          <OutAttribute> ByRef warningMessages As StringCollection _

) As Boolean

C#

public bool AddReplacementDriver (

          string pathToNewDriver,

          string replacesDriverId,

          out StringCollection errorMessages,

          out StringCollection warningMessages

)

Parameters

pathToNewDriver

The path to the driver files. All files in this directory and all subdirectories (and their files) will be packaged.

replacesDriverId

The GUID of the driver that this replaces.

errorMessages

Reference to a string collection that will contain all the error messages.

warningMessages

Reference to a string collection that will contain all the warning messages (including unreferenced file check).

Return Value

true if the new driver files passed signability; otherwise, false.

Remarks

An exception is thrown when:

  • The pathToDriver paramteror replacesDriverIdis parameter is null.

  • The pathToDriver parameter or replacesDriverId parameter is invalid or if the GUID for replacesDriverId was not found.

  • The PackageWriter object has already been disposed.

  • The method calls an invalid connection type.

  • The directory does not exist for the pathToDriver parameter.

  • The method called for an invalid connection type.

Notes on unreferenced file check:

  • If there is at least one unreferenced file, the following text will appear in warningMessages: "There was at least one file in the driver package that was not referenced by an .inf. Please only include files that are referenced by an .inf in the driver package. Refer to HLK's Microsoft Learn pages online for more information. For full list of unreferenced files in this package, see {log path}"

  • If the unreferenced file check failed to complete, the following text will appear in warningMessages: "Failed to analyze driver package for unreferenced files: {exception message}" This does not indicate whether the attached files were referenced or not, just that the check was not able to properly run.

  • If all attached files were properly referenced, warningMessages will not contain any messages pertaining to the unreferenced file check.

  • Every time AddReplacementDriver is run, a new log is generated (located at {drive letter}\HLK\JobsWorkingDir\UnreferencedFileLogs\UnreferencedFiles_{timestamp}.txt), even if all attached files were referenced.

The unreferenced file check supports most compressed files.

  • If a file is compressed and its extension ends in “_”, there will be no unreferenced file warning so long as the decompressed version of the file is properly referenced by the .inf.

  • If a .cab is included as a source location in the .inf’s SourceDisksNames section, HLK will examine the .cab’s contents during the unreferenced file check.

  • If a .cab is referenced as a driver file in the .inf, it will be treated as such during the unreferenced file check, and the .cab’s contents will not be examined.

What is not supported:

  • Attaching compressed .cat files.

  • Attaching double-compressed files (e.g. A user compresses a file individually, and then packs the already-compressed file into a cab. Or a user compresses files into a .cab, and then compresses the .cab a second time so it now ends with an underscore).

For info on log format and how to retrieve the list of unreferenced files, see Creating a Package. For tips on resolving unreferenced file warning, see Add driver and supplemental content to your package.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

  • Last updated on