About Reporting Configuration Manager Custom Action Progress

 

Updated: November 1, 2013

Applies To: System Center 2012 Configuration Manager, System Center 2012 Configuration Manager SP1, System Center 2012 R2 Configuration Manager

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.

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.

System_CAPS_noteNote

Typically, you should report progress information if the action takes more than one minute to run.

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.

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.

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 variable, _SMSTSOrgName. For more information, see IProgressUI::ShowActionProgress 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.

Show: