Show-ADTInstallationWelcome
SYNOPSIS
Show a welcome dialog prompting the user with information about the deployment and actions to be performed before the deployment can begin.
SYNTAX
None (Default)
Show-ADTInstallationWelcome [-CloseProcesses <ProcessObject[]>] [-Silent] [-CloseProcessesCountdown <UInt32>]
[-ForceCloseProcessesCountdown <UInt32>] [-PromptToSave] [-PersistPrompt] [-BlockExecution] [-AllowDefer]
[-AllowDeferCloseProcesses] [-DeferTimes <UInt32>] [-DeferDays <UInt32>] [-DeferDeadline <String>]
[-NoMinimizeWindows] [-NotTopMost] [-ForceCountdown <UInt32>] [-CustomText] -Title <String> -Subtitle <String>
-DeploymentType <DeploymentType> [<CommonParameters>]
CheckDiskSpace
Show-ADTInstallationWelcome [-CloseProcesses <ProcessObject[]>] [-Silent] [-CloseProcessesCountdown <UInt32>]
[-ForceCloseProcessesCountdown <UInt32>] [-PromptToSave] [-PersistPrompt] [-BlockExecution] [-AllowDefer]
[-AllowDeferCloseProcesses] [-DeferTimes <UInt32>] [-DeferDays <UInt32>] [-DeferDeadline <String>]
[-CheckDiskSpace] [-RequiredDiskSpace <UInt32>] [-NoMinimizeWindows] [-NotTopMost] [-ForceCountdown <UInt32>]
[-CustomText] -Title <String> -Subtitle <String> -DeploymentType <DeploymentType> [<CommonParameters>]
DESCRIPTION
The following prompts can be included in the welcome dialog:
- Close the specified running applications, or optionally close the applications without showing a prompt (using the
-Silentswitch). - Defer the deployment a certain number of times, for a certain number of days or until a deadline is reached.
- Countdown until applications are automatically closed.
- Prevent users from launching the specified applications while the deployment is in progress.
EXAMPLES
EXAMPLE 1
Show-ADTInstallationWelcome -CloseProcesses iexplore, winword, excel
Prompt the user to close Internet Explorer, Word and Excel.
EXAMPLE 2
Show-ADTInstallationWelcome -CloseProcesses @{ Name = 'winword' }, @{ Name = 'excel' } -Silent
Close Word and Excel without prompting the user.
EXAMPLE 3
Show-ADTInstallationWelcome -CloseProcesses @{ Name = 'winword' }, @{ Name = 'excel' } -BlockExecution
Close Word and Excel and prevent the user from launching the applications while the deployment is in progress.
EXAMPLE 4
Show-ADTInstallationWelcome -CloseProcesses @{ Name = 'winword'; Description = 'Microsoft Office Word' }, @{ Name = 'excel'; Description = 'Microsoft Office Excel' } -CloseProcessesCountdown 600
Prompt the user to close Word and Excel, with customized descriptions for the applications and automatically close the applications after 10 minutes.
EXAMPLE 5
Show-ADTInstallationWelcome -CloseProcesses @{ Name = 'winword' }, @{ Name = 'msaccess' }, @{ Name = 'excel' } -PersistPrompt
Prompt the user to close Word, MSAccess and Excel. By using the PersistPrompt switch, the dialog will return to the center of the screen every couple of seconds, specified in the config.psd1, so the user cannot ignore it by dragging it aside.
EXAMPLE 6
Show-ADTInstallationWelcome -AllowDefer -DeferDeadline '25/08/2013'
Allow the user to defer the deployment until the deadline is reached.
EXAMPLE 7
Show-ADTInstallationWelcome -CloseProcesses @{ Name = 'winword' }, @{ Name = 'excel' } -BlockExecution -AllowDefer -DeferTimes 10 -DeferDeadline '25/08/2013' -CloseProcessesCountdown 600
Close Word and Excel and prevent the user from launching the applications while the deployment is in progress.
Allow the user to defer the deployment a maximum of 10 times or until the deadline is reached, whichever happens first.
When deferral expires, prompt the user to close the applications and automatically close them after 10 minutes.
PARAMETERS
-CloseProcesses
Name of the process to stop (do not include the .exe). Specify multiple processes separated by a comma. Specify custom descriptions like this: @{ Name = 'winword'; Description = 'Microsoft Office Word'},@{ Name = 'excel'; Description = 'Microsoft Office Excel'}
Type: ProcessObject[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Silent
Stop processes without prompting the user.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-CloseProcessesCountdown
Option to provide a countdown in seconds until the specified applications are automatically closed. This only takes effect if deferral is not allowed or has expired.
Type: UInt32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-ForceCloseProcessesCountdown
Option to provide a countdown in seconds until the specified applications are automatically closed regardless of whether deferral is allowed.
Type: UInt32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-PromptToSave
Specify whether to prompt to save working documents when the user chooses to close applications by selecting the "Close Programs" button. Option does not work in SYSTEM context unless toolkit launched with "psexec.exe -s -i" to run it as an interactive process under the SYSTEM account.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-PersistPrompt
Specify whether to make the Show-ADTInstallationWelcome prompt persist in the center of the screen every couple of seconds, specified in the config.psd1. The user will have no option but to respond to the prompt. This only takes effect if deferral is not allowed or has expired.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-BlockExecution
Option to prevent the user from launching processes/applications, specified in -CloseProcesses, during the deployment.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-AllowDefer
Enables an optional defer button to allow the user to defer the deployment.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-AllowDeferCloseProcesses
Enables an optional defer button to allow the user to defer the deployment only if there are running applications that need to be closed. This parameter automatically enables -AllowDefer
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-DeferTimes
Specify the number of times the deployment can be deferred.
Type: UInt32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-DeferDays
Specify the number of days since first run that the deployment can be deferred. This is converted to a deadline.
Type: UInt32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-DeferDeadline
Specify the deadline date until which the deployment can be deferred.
Specify the date in the local culture if the script is intended for that same culture.
If the script is intended to run on EN-US machines, specify the date in the format: "08/25/2013" or "08-25-2013" or "08-25-2013 18:00:00"
If the script is intended for multiple cultures, specify the date in the universal sortable date/time format: "2013-08-22 11:51:52Z"
The deadline date will be displayed to the user in the format of their culture.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-CheckDiskSpace
Specify whether to check if there is enough disk space for the deployment to proceed.
If this parameter is specified without the RequiredDiskSpace parameter, the required disk space is calculated automatically based on the size of the script source and associated files.
Type: SwitchParameter
Parameter Sets: CheckDiskSpace
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-RequiredDiskSpace
Specify required disk space in MB, used in combination with CheckDiskSpace.
Type: UInt32
Parameter Sets: CheckDiskSpace
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-NoMinimizeWindows
Specifies whether to minimize other windows when displaying prompt. Default: $false.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-NotTopMost
Specifies whether the window is the topmost window.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-ForceCountdown
Specify a countdown to display before automatically proceeding with the deployment when a deferral is enabled.
Type: UInt32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-CustomText
Specify whether to display a custom message specified in the string.psd1 file. Custom message must be populated for each language section in the string.psd1 file.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-DeploymentType
The deployment type. Default: the session's DeploymentType value.
Type: DeploymentType
Parameter Sets: (All)
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Subtitle
Subtitle of the prompt. Default: the application deployment type.
Type: String
Parameter Sets: (All)
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Title
Title of the prompt. Default: the application deployment name.
Type: String
Parameter Sets: (All)
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
INPUTS
None
You cannot pipe objects to this function.
OUTPUTS
None
This function does not return any output.
NOTES
An active ADT session is NOT required to use this function.
The process descriptions are retrieved via Get-Process, with a fall back on the process name if no description is available. Alternatively, you can specify the description yourself with a '=' symbol - see examples.
The dialog box will timeout after the timeout specified in the config.psd1 file (default 55 minutes) to prevent Intune/SCCM deployments from timing out and returning a failure code. When the dialog times out, the script will exit and return a 1618 code (SCCM fast retry code).
Tags: psadt
Website: https://psappdeploytoolkit.com
Copyright: (C) 2025 PSAppDeployToolkit Team (Sean Lillis, Dan Cunningham, Muhammad Mashwani, Mitch Richters, Dan Gough).
License: https://opensource.org/license/lgpl-3-0
RELATED LINKS
https://psappdeploytoolkit.com/docs/reference/functions/Show-ADTInstallationWelcome