An Active Setup Primer

If you frequent ITNinja, you'll find it not too uncommon a suggestion to "use Active Setup" to address a problem. Normally it is because a member is asking about how to change a HKCU value or delete a file from a user profile path. This article is intended to help explain such a recommendation by offering some detail on just what Active Setup is and how it works.

If you are familiar with the registry's RunOnce capability, you'll find Active Setup is indeed very similar in the functionality it provides. However, Active Setup is better for deployment purposes because you can see what has been executed by looking to the registry. RunOnce on the other hand, removes itself after it executes so there is no inherent record of it.

If you want to manipulate a user profile, you need a user to be logged in. As such a logon script is also a fine candidate for injecting changes to HKCU. Just add the change to the logon script and users will get the changes as they log in. But you don't want it to run every time they log in, so it's best to add a condition: if change 1 has not run, execute change 1. This same logic is essentially what Active Setup provides (outside of the logon script).

Obviously if you don't have a logon script, implementing one for a simple change would be undesirable. However, I think one of the best reasons to choose Active Setup over a logon script update is that you can keep your deployment related tasks in your deployment package. You can leverage Active Setup for user specific changes right within your MSI package, task sequence or deployment script so they don't become disconnected from the application deployment.

You've probably seen Active Setup in action before but may not have known it was "Active Setup". For instance, the first time you logged into Windows you may have seen a status window advising you it was "setting up personalized settings". Essentially, Active Setup is a mechanism to trigger one or more actions to be run once per user. Windows looks to the Active Setup area of the machine profile (HKLM) and sees if it matches the current user profile (HKCU) copy of the subkey, runs any jobs necessary and then makes HKLM and HKCU match (signifying jobs have run and not need to run again). To be specific…

The Windows logon process looks at all subkeys under:

HKEY_LOCAL_MACHINE\Software\Microsoft\Active Setup\Installed Components\[ID]

Where [ID] represents a unique name for the component. There are a couple values to understand under each:

  • (default)
    • The display name of the job
  • Version
    • Versions are checked for a match, which handy if you need to rerun a job or tweak one because you don’t have to come up with a new unique name for the job
  • StubPath
    • The command line to be executed for the job 

Windows checks for a match in the same path under the user profile at:

HKEY_CURRENT_USER\Software\Microsoft\Active Setup\Installed Components\[ID]

For each job not listed and matching in HKCU (meaning it has not been executed) the StubPath command is executed and the user profile is updated to match that of the machine path (signifying it has been executed and does not need to run again in the future).

To see this in action, fire up the registry editor and create the following:

HKEY_LOCAL_MACHINE\Software\Microsoft\Active Setup\Installed Components\Test

  • (default)
    • Active Setup Test
  • Version
    • 1
  • StubPath
    • Notepad.exe

Log out and back in again. Windows will see that your profile has not run "Test" yet and will execute "notepad.exe". If this were a simple command line, it may run so quick that you don't get to see it so by running notepad we essentially hold the job open until notepad is closed. As such, you’ll be able to see the "Personalized Settings" dialog stating it is running "Active Setup Test" (our friendly name for the job).

Visit the HKCU path at HKEY_CURRENT_USER\Software\Microsoft\Active Setup\Installed Components\ and you'll see that our "Test" job isn't listed yet. Close notepad to let the job complete, refresh the Registry Editor display and you’ll see it is now listed as expected. With those values present, Windows will know not to run the job again for your user profile.

Deleting the value from HKCU will cause it to run again, but if you want to run it again, the best way to go about it is to update its version value. The StubPath can be a command line or script changing or deleting whatever necessary, but keep in mind that like a logon script it runs with user credentials and so cannot manipulate HKLM or write to most areas outside of the profile so take care and use this strictly for user profile related changes (leaving application installation or larger changes to your application deployment mechanism).

I hope you find this helpful. To see other content tagged with "Active Setup", see its tag home page here: http://www.itninja.com/tag/active-setup


  • Great writeup Bob

    I would like to mention though that in my opinion the single biggest drawback of Active Setup is that there's no error checking whatsoever on the actions you run

    If it's successful, great. If it fails however, it will not run again for that user. - pjgeutjens 9 years ago
    • Thanks, it is indeed on the user to validate success and write to logs if desired. On the plus side, a failure won't just keep running forever ;) - bkelly 9 years ago
  • One thing that helps me prevent the error checking issue is that I only use Active Setup as part of an MSI, and I only incorporate it by importing a REG key which performs a repair and leverages the package properties. - vjaneczko 9 years ago
  • I would like to add a few nuggets of information about Active Setup that I have encountered over the years. First of all, if Active Setup runs and the code stalls, it will hang the machine, so it should always be written with error trapping that will avoid a hang under all circumstances.
    Secondly, never call an MSI via Active Setup. I have seen many instances where an MSI operation gets started during bootup (eg an update or a self healing operation), and the MSI called by active setup therefore errors out because you cannot run two MSIs concurrently, but HKCU is still updated. Thus the active setup never gets run.
    On a 64 bit system, you can use both 32 bit active setup and 64 bit active setup, and if I recall correctly, the 32 bit entries get run first.
    You can also control the order in which active setups run - examine the existing keys in HKLM and some have a > at the start of the registry entry, and these get run LAST. There also seems to be a correlation that GUIDS are run in numerical order. - EdT 9 years ago
    • Excellent tips EdT, thank you! - bkelly 9 years ago
  • One final thing I forgot to add. The version field delimiter needs to be a comma. There is no problem if you use integer values for the version field, eg 1 or 2, but if you want to put in a version equivalent to the product version, eg 3.5.75 then you need to specify it as 3,5,75 within active setup otherwise it does not get processed correctly. - EdT 9 years ago
This post is locked
This website uses cookies. By continuing to use this site and/or clicking the "Accept" button you are providing consent Quest Software and its affiliates do NOT sell the Personal Data you provide to us either when you register on our websites or when you do business with us. For more information about our Privacy Policy and our data protection efforts, please visit GDPR-HQ