RunOnce Registry Entries

The system supports a registry key, RunOnce, that can be used to specify commands that the system will execute one time and then delete. Immediately after a device has been installed, Setup executes all commands stored under the RunOnce key, then removes the commands. Additionally, each time the system boots, it executes all commands stored under the RunOnce key, then removes them. Thus, if you place a command under the RunOnce key, you cannot easily predict when it will execute.

For device installations, RunOnce registry entries can be created using add-registry-sections, which are referenced by INF AddReg directives. The registry root and subkey values are as follows:

HKLM,"Software\Microsoft\Windows\CurrentVersion\RunOnce"

The value-entry-name string is omitted from a RunOnce registry entry. The type of the entry, which is indicated by the flags value, must be either REG_SZ or REG_EXPAND_SZ. For an entry of type REG_SZ (the default), the flags value can be omitted.

The value parameter in a RunOnce entry is a quoted string that has the following form:

"Rundll32[.exe] DllName,EntryPoint[Arguments]"

Consider the following guidelines when you create a value string entry:

• Rundll32 can appear either with or without its .exe file name extension.
• DllName is the full path to a DLL or executable image. Except for a required terminating comma, the expression must not otherwise contain any commas. If no file name extension is supplied, the default extension is .dll.
• EntryPoint is the name of the entry point within the DLL indicated by DllName.
• Arguments is an optional substring containing any arguments that must be passed to the specified DLL.
• Exactly one space must separate the EntryPoint string from the Arguments substring.

Following is an example add-registry-section entry that stores a command and its arguments under the RunOnce key:

;; WDMAud swenum install

HKLM,%RunOnce%,"WDM_WDMAUD",,\
"rundll32.exe streamci.dll,StreamingDeviceSetup %WDM_WDMAUD.DeviceId%,%KSNAME_Filter%,%KSCATEGORY_WDMAUD%,%17%\WDMAUDIO.inf,WDM_WDMAUD.Interface.Install"

[Strings]
RunOnce = "SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnce"
WDM_WDMAUD.DeviceId = "{CD171DE3-69E5-11D2-B56D-0000F8754380}"
KSNAME_Filter = "{9B365890-165F-11D0-A195-0020AFD156E4}"
KSCATEGORY_WDMAUD = "{3E227E76-690D-11D2-8161-0000F8775BF1}"

The following rules apply to the use of RunOnce entries for device installations:

• These registry entries must be used solely for installations of software-only devices that are enumerated by SWENUM, the software device enumerator.
• RunOnce entries must consist only of calls to rundll32.exe. Otherwise, Microsoft will not digitally sign the driver package.
• The code to be executed must not prompt for user input.
• Server-side installations execute in a system context. For this reason, you must be certain that the code to be executed contains no security vulnerabilities and that file permissions prevent the code from being maliciously modified.