While a custom action is running on a System Center 2012 R2 Configuration Manager client, it can report progress information that is used to display a progress indicator.
You use the COM automation interface, IProgressUI::ShowActionProgress Method, to report progress information to the task sequence environment and to show a progress indicator.
IProgressUI::ShowActionProgress is implemented in the COM class, ProgressUI Client COM Automation Class, which is an out-of-process COM object in TSProgressUI.exe.
ProgressUI in the Task Sequence Environment
Before the task sequence runs, ProgressUI is registered and then, when the task sequence finishes, it is unregistered. In the source operating system, ProgressUI runs under the logged-on user credentials. If no user is logged in when the task sequence runs, the registration for the COM object fails. In the target operating system, and in Windows PE, ProgressUI runs under the system account.
In your custom action you must do the following to report the progress of your custom action and display a progress indicator.
|Typically, you should report progress information if the action takes more than one minute to run.|
Determining Whether the Progress Indicator Should Be Displayed
Using the following logic, you can use environment variables to determine whether the progress indicator should be displayed.
If you are running in WindowsPE ( _SMSTSInWinPE == “true”), or
If you are running in full operating system post installation (_SMSTSReturnToGINA==”true”), or
If the task sequence is started from media (_SMSTSLaunchMode is “CD”, “DVD” or “USB”), or
If the task sequence is running in stand-alone mode (_SMSTSStandAloneMode==”true”), or
If the show progress UI flag is set (_SMSTSShowProgressUI == “true”), the progress indicator should be displayed; otherwise, it should not be displayed.
Creating the COM ProgressUI Object
You create a ProgressUI object by using the same technique that you use with any COM object. In C++ you use CoCreateInstance. In C# you add a reference to SMS TSE Progress UI, and in your source code you create an instance of the ProgressUILib.ProgressUIClass class.
In VBScript, call CreateObject with Microsoft.SMS.TsProgressUI.
For an example of creating a COM object in VBSript and C#, see How to Specify the Supported Platforms for a Driver.
Getting the Required Environment Variables
Several environment variables contain information that
you must pass to the IProgressUI::ShowActionProgress method.
For example, the organization name that is needed for the
pszOrgName parameter is available from the environment
_SMSTSOrgName. For more information, see
Method. For information about reading task sequence environment
variables, see How to Use Task Sequence
Variables in a Running Configuration Manager Task Sequence.
Call IProgressUI::ShowActionProgress to show the progress indicator by using the information that is retrieved from the environment variables. To pass the current percentage progress, you use the parameters uActionExecStep and uActionExecMaxStep. For example, if you pass the value 2 in uActionExecStep and pass the value 10 in uActionExecMaxStep, then the percentage completion of the action is 20 percent.