RunOnce Request

  • Article

5/10/2007

This resource is used to execute an application during first boot of the run-time image, after first boot, or after every logon. This functionality is added to the run-time image as one of three registry keys:

  • HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run
  • HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnce
  • HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnceEx

Each of these keys is described in detail under the definition for Flags that follows.

The following extended properties can be set for the RunOnce Request in Component Designer or Target Designer.

  • Arguments

    Type Required or optional

    String

    Optional

    Specifies the command-line arguments, if any, to pass to the application that is specified by FilePath. Arguments that contain paths should be specified by using environment variables in path names. For more information, see Predefined System Environment Variables.

    The default value is an empty string.

  • ComponentVSGUID

    Type Required or optional

    GUID

    Not applicable

    Reserved for Microsoft.

  • FilePath

    Type Required or optional

    String

    Required

    Specifies the path and file name of the executable file on the target device. This value must be a fully qualified path, for example, %11%\MyRunOnceApp.exe. Use environment variables in path names. For more information, see Predefined Predefined System Environment Variables.

  • Flags

    Type Required or optional

    DWORD

    Required

    Specifies a value that indicates what type of Run operation to perform, 0, 1, or 2. The type of run operation dictates when to execute the application specified by FilePath. The following list shows the possible values:

    • 0: Run.
      The Run key is processed after every logon, either by the Explorer shell, if it is present, or by First Boot Agent (FBA), if a custom shell, Command shell, or Task Manager shell is used. If FBA processes this key, it does so after every logon, not during first boot as it normally would. Typically, this flag is used to load Systray applications, launch services in executables, hide autostart applications, or hide background processes.
    • 1: RunOnce. Default.
      The RunOnce key is processed only once, by FBA, after Plug and Play device enumeration and DLL registration processing have completed. The values of this registry key are deleted from the registry after it is processed, so that it will not run again. Typically, this flag is used when a reboot is required, such as for a DLL or OCX registration, or for cleaning up a setup or an uninstall.
    • 2: RunOnceEx.
      The RunOnceEx key is processed only once, by the Explorer shell, after the first logon. The values of this registry key are deleted from the registry after it is processed, so that it will not run again. If the Explorer shell is not present, this key is ignored. Typically, this flag is used for a process that runs only once, and that either cannot be run correctly by FBA or requires the system to be fully operational.

    These values are stored in the registry keys Run, RunOnce, or RunOnceEx in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\.

  • ValueName

    Type Required or optional

    String

    Required

    Specifies the name of the REG_SZ registry value that will be used to hold the data specified by FilePath.

See Also

Tasks

Adding a RunOnce Request to a Run-Time Image
Automatically Joining a Domain with a Custom Application

Concepts

RunOnce Request Types and Scenarios

Other Resources

Custom Resources
First Boot Agent