Fulcrum Blog

Article: A Deep Dive into Active Setup: Part 2

Apr 13, 2020 | blog |

by Jacob Kimbrough

Consulting Architect

Jacob Kimbrough is a Consulting Architect at Fulcrum Technology Solutions. Kimbrough joined the Infrastructure team in 2014.

In Part 1, we looked at what Active Setup is and some use cases that I solved using Active Setup. In this part, we’ll get technical and look at the inner workings of an Active Setup component along with some testing methods.

Let’s Get Technical

Construction
Active Setup consists of a “master” list of components to execute, which we call the system part. (A component is a registry key with some associated values). When a component is executed for a user, part of its registry entries (the system part) is copied to the user’s profile for tracking purposes. We call this the user part.

Active Setup’s system part can be located in either of these two locations:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Active Setup\Installed Components\{Your made-up GUID or string here}
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Active Setup\Installed Components\{Your made-up GUID/string here}

Active Setup’s user part can be located in either of these two locations:
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Active Setup\Installed Components\{Your made-up GUID or string here}
HKEY_CURRENT_USER\SOFTWARE\Wow6432Node\Microsoft\Active Setup\Installed Components\{Your made-up GUID/string here}

At logon, explorer.exe looks through each component and determines whether it is eligible to run based on several criteria:

  1. Is the component’s IsInstalled value set to 1 (or defaulted to 1)?
  2. Has this version of the component already been run for this user? (We compare the system part’s Version identifier to the user part’s Version identifier)
  3. Does the Locale match? (We compare the system part’s Locale identifier to the user part’s Locale identifier in a case-sensitive way)

How to Use Active Setup
To use Active Setup, create a key in the HKEY_LOCAL_MACHINE registry hive for each item that you want to have executed in the user’s context at logon.

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Active Setup\Installed Components\{Your made-up GUID or string here}
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Active Setup\Installed Components\{Your made-up GUID/string here}

Registry value Type Required Description
(Default value) REG_SZ No This is the name that will display to the user (albeit briefly) when the Active Setup dialog box displays.  Not required, but certainly recommended.
IsInstalled REG_DWORD No Value of 0 or 1.

·        ‘0’ means that this component is disabled and will be ignored.

·        ‘1’ means that this component will run once per user.

Default value is ‘1’ if you don’t specify a value.

Locale REG_SZ No This is an arbitrary string that is supposed to indicate the language of this Active Setup component.  This string can be any value, and is not used to match anything within the user’s Culture settings or the system’s language.

 

Many of the built-in components just specify an asterisk/wildcard “*”.  Really, Locale is an unnecessary complication.

 

Note that when this value is matched against the user part of the Active Setup component, the match is case-sensitive.

Version REG_SZ Yes Arbitrary string value.  But you want to use numbers.

 

You can use whole numbers (1/2/3) or comma-delimited formal version string (“1,0,0,0”).  Inexplicably, you can not use a dot/decimal notation for versions (“1.0.0.0”).  Or letters.  (Well, you can use letters, but you’ll have trouble if you want to iterate your component down the road).

Once the Active Setup component is run, this Version value is copied to the user’s registry.  If you ever need to update your component – say, to run a different command or alter the command slightly, simply head to this registry value and increment the Version.  When the user logs in, explorer.exe look at the value the user has for Version.  Does it match?  If not, we will run StubPath.

StubPath REG_SZ
REG_EXPAND_SZ
Yes This is a command line.  You can place anything here than you could place in a Start | Run window or from a Windows command line.

If this Active Setup component is valid, enabled, and eligible to run, this is what will be executed.

If you need to run more than one command line to get something done, no problem!  Simply create additional Active Setup components for your additional command lines.

A simple example
Here is an example of an Active Setup component that runs a script. (Note I’ve left off some optional components that I do not need, and that these examples are in a .reg file format):

[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Active Setup\Installed Components\{2930f291-6d59-42ec-852b-f58e2cd6807a}_A]
@=”Scripted actions for Application X”
“Version”=”1”
“StubPath”=”C:\\Windows\\GetAppReady.cmd”

A more complex example
Now, a more complex example. Why is this complex? Because we need quotes in our StubPath, as well as backslashes, which we need to escape. Also, instead of a GUID, I’m using a string as the name of my registry key.

[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Active Setup\Installed Components\FulcrumActiveSetupComponent]
@=”Scripted actions for Application Y”
“Version”=”1,0”
“StubPath”=”cmd.exe /c PowerShell.exe -ExecutionPolicy Bypass -File \”C:\\Program Files\\Scripts\\MyScript.ps1\””

How Can I Test This?
During your development phase, you might want to test your Active Setup components. Maybe you have repeated your R&D cycles many times to get it just right, or maybe you want to test remotely on a user’s PC. How can you manually launch Active Setup? Here are some options:

  1. Log off and log back on to the PC
  2. Terminate exe and re-launch it (tricky to do in the user context from a command line as SYSTEM, but it can be done)
  3. From a command prompt running in the user context, execute:
    %systemroot%\system32\runonce.exe /AlternateShellStartup

That’s it for Part 2. In Part 3, we’ll discuss some all-important gotchas that have, in the past, cost me days of R&D to find and get past. I’ll also have some suggestions for long-running scripts, hiding windows from the user, and more.

References
https://helgeklein.com/blog/2010/04/active-setup-explained/
https://www.itninja.com/blog/view/appdeploy-articles-activesetup?from=appdeploy.com

[feather_share show=”facebook, twitter, linkedin,” hide=”reddit, tumblr, pinterest, google_plus, mail”]
[wpad-comment-form id=”311″]

The Fulcrum Difference

At Fulcrum Technology Solutions, we differentiate ourselves from other technology- and business-consulting firms with a unique guarantee: when you hire Fulcrum, we commit to finish the job. Whether working under a time-and-materials contract or a cost-plus arrangement, we will not leave until we’ve delivered exactly what we said we’d do. Our word defines us, and motivates us to give you the service that you deserve!

2603 Augusta Dr. Suite 1325, Houston, TX 77057

Phone: 832-954-2800 

footer-linkedfbtwittercontact_icon

Share This