PSADT.ToastNotification Extension
Extension for PowerShell App Deployment Toolkit that replace all the windows and dialogs with Toast Notifications with a lot of visual and functional improvements.
Features
- Administrative rights not needed.
- Wraps the original functions, so no script modification needed.
- SYSTEM raised Toast Notifications can interact with logged in no Administrator user.
- Ability to interact with the notifications using events or protocols.
- Can search for closing apps using wildcards.
- Can search for closing apps based on windows title or process path using wildcards.
- Added array of never kill applications (even if added for closing).
- Added array of never block applications (they can be killed but not blocked).
- Limit functions timeout to InstallationUITimeout.
- Ability to use MUI cache applications name if exists.
- Highly customizable Toast Notification visual schemes.
- Dynamically update running applications with icons and extended applications information.
- Fallback to original Windows Forms and dialogs if any error occurs.
- New dedicated strings with multilanguage support.
Functions (wrappers) and improvements
Show-InstallationWelcome
-
Now you can search for processes using
like
operator. If you include any wildcard character, the evaluating operator will be-like
instead of-eq
. The search objectAcroRd*=Adobe Acrobat Reader
matches 32/64 bits version of the application, only currently running processes will be added to the$ProcessObjects
. See about Comparison Operators - PowerShell | Microsoft Learn. -
For windows title search use
title:...
as suffix, if any process window validates the filter it will be added to the$ProcessObjects
. Wildcards supported,title:*Adobe*
will add any process that is currently running and the title is like*Adobe*
. Notitle:...=Application Name
supported. See about Comparison Operators - PowerShell | Microsoft Learn. -
For process path search use
path:...
as suffix, all the currently running processes validating the filter will be added to the$ProcessObjects
. Wildcards supported,path:$($env:ProgramFiles)\*Office*\*
will add any process that is currently running and the path is like$($env:ProgramFiles)\*Office*\*
. Nopath:...=Application Name
supported. See about Comparison Operators - PowerShell | Microsoft Learn. -
The closing applications evaluation removes processes that are included in
CriticalProcesses_NeverKill
, they won`t be added and a warning appears in console/log. -
Internal function mechanism is kept for backward compatibility but, if the switch
-PersistPrompt
is not present, the user can dismiss or close the notification and aTimeout
result is returned. -
If the
-BlockExecution
switch is used, any process included inCriticalProcesses_NeverBlock
won`t be added for blocking and a warning appears in console/log.
Show-BalloonTip
-
Shows a long duration Toast Notification if the
$BalloonTipTime
is greater than10000
ms. -
No need to call any external script, the Toast Notification always shows itself like if
$NoWait
was$true
. -
For more options see the Customizable visual style section.
Show-DialogBox
-
The buttons get the translated string using the Data Extraction Extension to match the user language, the
InstallationUI_LanguageOverride
is omitted like original dialog box. -
If the
$Timeout
is bigger than$configInstalltionUITimeout
you can useLimitTimeoutToInstallationUI
config option to limit the timeout. -
You can use
ShowAttributionText
config option to show a subtle text indicating the auto-dismiss timeout. -
For more options see the Customizable visual style section.
Show-InstallationRestartPrompt
-
The shutdown command calls
shutdown.exe /r /f /t $SilentCountdownSeconds
instead ofRestart-Computer
since sometimes the cmdlet does not work. -
Ability to show a warning icon by using
InstallationRestartPrompt_ShowIcon
config option. -
You can use
ShowAttributionText
config option to show a subtle text indicating the auto-restart timeout. -
If the parameter
$NoCountdown
is$false
the Toast Notification will show a progress bar with the timeout to auto-restart. -
Closing or dismissing the Toast Notification works like the
Minimize
button. -
For more options see the Customizable visual style section.
Show-InstallationPrompt
-
If the
$Timeout
is bigger than$configInstalltionUITimeout
you can useLimitTimeoutToInstallationUI
config option to limit the timeout. -
Asynchronously behavior maintained like original function.
-
You can use
ShowAttributionText
to show a subtle text indicating the auto-dismiss timeout. -
For more options see the Customizable visual style section.
Show-InstallationProgress
-
Defines the new variable
InstallationProgressFunctionCalled
that works like a switch indicating thatClose-InstallationProgress
should be called. -
You can use
ShowAttributionText
config option to show a subtle text indicating the deployment progress message. -
You can use
InstallationProgress_ShowIndeterminateProgressBar
config option to show an indeterminate progress bar. -
For more options see the Customizable visual style section.
Internal functions (wrappers) and improvements
Get-RunningProcesses
-
The function has changed, now it receives a
[PSCustomObject[]]
as input, backward compatibility kept. -
If any
CriticalProcesses_NeverKill
matches any process name or filters, it won`t be added and a warning appears in console/log.
- The output object array contains the process name, description, path and company.
Show-WelcomePrompt
-
If you do not like the Continue button string like me, you can use
WelcomePrompt_ReplaceContinueButtonDeploymentType
and now the text will show the translated strings ofInstall
,Repair
orUninstall
based on the deployment type of the script. -
If the
$CloseAppsCountdown
is bigger than$configInstalltionUITimeout
you can useLimitTimeoutToInstallationUI
to limit the timeout. -
You can use
ShowAttributionText
to show a subtle text indicating the auto-deferral or auto-continue timeout. -
Ability to show more than the process name by using
ShowApplicationsIcons
andShowExtendedApplicationsInformation
. -
By design the Toast Notification can only show up to 5 applications, additional ones will be grouped in the last item. You can reduce the amount of showed row by using
WelcomePrompt_MaxRunningProcessesRows
. -
The new strings react to the deployment type showing correctly if the application is running an
Installation
,Repairing
orUninstallation
process and the translated string will be integrated in the showed text as well as the count of running applications to close. -
For more options see the Customizable visual style section.
Close-InstallationProgress
-
Wraps the original function but removes any background event or job.
-
The original function is only called if the
Show-InstallationProgress
function was used before.
Exit-Script
- Wraps the original function but removes any created variable before.
New-BlockExecutionToastNotificationTemplate
-
Creates the Toast Notification template that will be raised when a blocked application tries to run.
-
Puts a list at the bottom of the Toast Notification showing the blocked applications.
-
The Toast Notification shows which applications is being
installed
,repaired
oruninstalled
in the title. -
For more options see the Customizable visual style section.
Show-BlockExecutionToastNotification
-
Shows a previously created Toast Notification if any blocked application tries to run.
-
Ability to show more than the process name by using
ShowApplicationsIcons
andShowExtendedApplicationsInformation
. -
For more options see the Customizable visual style section.
Block-AppExecution
-
The function has changed, now it receives a
[PSCustomObject[]]
as input, backward compatibility kept. -
Changed the logic to detect if user has administrative rights.
-
Fixed a bug since version
3.8.4
with the task scheduled name. -
If the process that will be blocked has information in the Image File Execution Option registry key, it will be backed up and restored after the deployment process or reboot.
-
Now the blocked application registry subkey are recreated volatile, if any error occurs, with a logoff/reboot all will be unlocked (the original scheduled task is no longer needed but kept for backward compatibility). See PSADT.VolatilePaths Extension
-
The remove blocked application scheduled tasks auto-delete itself after running.
-
New scheduled task that restores the backed up Image File Execution Option per process that auto-deletes itself after execution.
-
Uses new cmdlets to register the scheduled tasks.
-
The users who tries to run a blocked application is registered in log by default.
-
Minor backward compatible changes to the VBS script to capture the blocked application process.
Unblock-AppExecution
-
Changed the logic to detect if user has administrative rights.
-
Tries to remove the Debugger property per process, but if any process remains blocked, the scheduled task will retry hourly.
-
Restores the backed up Image File Execution Option per process by calling the scheduled task created.
Internal functions
This set of functions are internals and are not designed to be called directly
- New-DynamicFunction - Defines a new function with the given name, scope and content given.
- New-ToastNotificationAppId - Registers the application identifier in registry.
- New-ToastNotificationProtocol - Registers the protocol in registry.
- New-ToastNotificationProtocolCommandFile - Creates a new file with the script used by the protocol.
- Remove-ToastNotificationAppId - Removes an application identifier from the registry.
- Remove-ToastNotificationProtocol - Removes a protocol from the registry.
- Compare-ToastNotificationAppId - Compares and verifies the application identifier data in the registry.
- Compare-ToastNotificationProtocol - Compares and verifies the correct operation of the protocol.
- Test-ToastNotificationAppId - Unregister and register again the AppId properties in registry.
- Test-ToastNotificationProtocol - Unregister and register again the protocol properties in registry.
- Test-ToastNotificationVisible - Determines if the previously raised notification is visible.
- Test-ToastNotificationAvailability - Determines whether the application identifier can raise notifications.
- Test-ToastNotificationExtension - Performs several tests to determine if notifications can be displayed.
- Get-ToastNotificationResult - Obtains the result of the execution and/or test of the protocol.
- Remove-ToastNotificationResult - Removes any previous result when using protocol.
- Clear-ToastNotificationHistory - Clear previously shown notifications from history.
- Register-WrappedToastNotificationEvent - Register a WinRT event by wrapping it in a compatible object.
- Register-ToastNotificationEvents - Registers the events triggered by the notification.
- Unregister-ToastNotificationEvents - Stops and removes previously registered events.
Configuration File
General options and extended configuration for the wrapped functions:
- WorkingDirectory: A valid directory or $variable. Will be created if not exists, will use $dirAppDeployTemp if not valid.
- TaggingVariable: A not null tag or $variable. Will use $installName if empty/null.
- ProtocolName: Name of the protocol with which the commands will be launched. Will use âpsadttoastnotificationâ if empty/null. CAUTION: do not use a known protocol as it can be overwritten in the registry!
- SubscribeToEvents: Attempts to register events raised by the Toast Notification object.
- LimitTimeoutToInstallationUI: If any wrapped function timeout exceeds the defined in the XML configuration, use that value.
- CriticalProcesses_NeverKill: Processes that, even if they are included, will not be closed by the Show-InstallationWelcome function.
- CriticalProcesses_NeverBlock: Processes that, even if they are included, will not be blocked by the Block-AppExecution function.
- InstallationWelcome_AlwaysParseMuiCacheAppName: Prefer MuiCache application name over -CloseApps description given.
- WelcomePrompt_MaxRunningProcessesRows: Maximum number of rows with running applications in the Toast Notification. Integer number between 1 and 5.
- WelcomePrompt_ShowCloseMessageIfCustomMessage: Shows the message warning that applications should be closed after the custom message.
- WelcomePrompt_ReplaceContinueButtonDeploymentType: Shows the deployment type action instead of the âContinueâ label in the button.
- BlockExecution_TemplateFileName: Name of the template that contains the blocked applications notification.
- InstallationProgress_ShowIndeterminateProgressBar: Defines if a progress bar is displayed simulating a loading or waiting state.
- InstallationRestartPrompt_ShowIcon: Shows a warning icon in the restart notification.
Options used by the Application that raise the Toast Notification:
The custom application identifier used to raise the Toast Notification is automatically registered system wide or per user and it is volatile, nothing remains in registry after logoff/reboot.
- AppId: Identifier of the application used to display the Toast Notification.
- DisplayName: Display name on Toast Notification used to display it.
- IconUri: Location of the icon to display in the notification.
- IconBackgroundColor: Icon background color.
- ShowInSettings: Allow registered application to be shown in Settings.
- AllowContentAboveLock: Allow Toast Notifications to show its content on lock screen.
- ShowInActionCenter: Allow Toast Notifications to stay in the Action Center.
Customizable visual style
Before editing the Toast Notification visual style see App notification content - Windows apps | Microsoft Learn
Not all the Toast Notifications included in the extension have the same configuration options.
- UpdateInterval: Interval in seconds at which the notification is updated. Integer number between 1 and 10.
- ShowAttributionText: Shows a small text indicating the automatic action of the toast notification when there is no countdown.
- ImageHeroShow: Defines if the top header image of the notification is shown.
- ImageHeroFileName: Top header image filename and extension, located in the .\SupportFiles\PSADT.ToastNotification folder.
- ImageAppLogoOverrideShow: Defines if the internal image of the notification is shown.
- ImageAppLogoOverrideFileName: Internal image filename and extension, located in the .\SupportFiles\PSADT.ToastNotification folder.
- ImageAppLogoOverrideCircularCrop: Defines if the internal image will be crop in a circular figure.
- ShowApplicationsIcons: Shows the applications icons (if apply).
- ApplicationsIconsSize: Sets the size of the applications icons, corresponding to 16x16, 32x32 and 48x48 at 100% scale factor. Default**: ExtraLarge.
- CollapseApplicationsIcons: Reduces the applications icons margins (if apply).
- ShowExtendedApplicationsInformation: Shows extended information per application, like MainWindowsTitle, Description, Company (if apply).
- ShowDialogIconAsAppLogoOverride: Replaces the AppLogoOverride image with the Dialog icon (if apply).
- DialogsIconsSize: Sets the size of the icons used by dialogs, corresponding to 16x16, 32x32 and 48x48 at 100% scale factor. Default**: Large.
- CollapseDialogsIcons: Reduces the dialogs icons margins (if apply).
- AudioSource: Sound file to play when displaying the notification or any of the system defined.
- AudioLoop: Defines if the sound is played in an indefinite loop.
- AudioSilent: If this value is true, then no sound will be played.
Requirements
- Powershell 5.1+
- PSAppDeployToolkit 3.8.4+
- PSADT.VolatilePaths Extension
- PSADT.DataExtraction Extension