Start-ADTProcessAsUser

SYNOPSIS

Invokes a process in another user's session.

SYNTAX

PrimaryActiveUserSession (Default)

Start-ADTProcessAsUser -FilePath <String> [-ArgumentList <String[]>] [-WorkingDirectory <String>] [-HideWindow]
 [-ProcessCreationFlags <CREATE_PROCESS>] [-InheritEnvironmentVariables] [-Wait] [-UseLinkedAdminToken]
 [-SuccessExitCodes <Int32[]>] [-ConsoleTimeoutInSeconds <UInt32>] [-IsGuiApplication] [-NoRedirectOutput]
 [-MergeStdErrAndStdOut] [-OutputDirectory <String>] [-NoTerminateOnTimeout]
 [-AdditionalEnvironmentVariables <IDictionary>] [-WaitOption <WaitType>] [-SecureArgumentList] [-PassThru]
 [<CommonParameters>]

AllActiveUserSessions

Start-ADTProcessAsUser -FilePath <String> [-ArgumentList <String[]>] [-WorkingDirectory <String>] [-HideWindow]
 [-ProcessCreationFlags <CREATE_PROCESS>] [-InheritEnvironmentVariables] [-Wait] [-AllActiveUserSessions]
 [-UseLinkedAdminToken] [-SuccessExitCodes <Int32[]>] [-ConsoleTimeoutInSeconds <UInt32>] [-IsGuiApplication]
 [-NoRedirectOutput] [-MergeStdErrAndStdOut] [-OutputDirectory <String>] [-NoTerminateOnTimeout]
 [-AdditionalEnvironmentVariables <IDictionary>] [-WaitOption <WaitType>] [-SecureArgumentList] [-PassThru]
 [<CommonParameters>]

SessionId

Start-ADTProcessAsUser -FilePath <String> [-ArgumentList <String[]>] [-WorkingDirectory <String>] [-HideWindow]
 [-ProcessCreationFlags <CREATE_PROCESS>] [-InheritEnvironmentVariables] [-Wait] -SessionId <UInt32>
 [-UseLinkedAdminToken] [-SuccessExitCodes <Int32[]>] [-ConsoleTimeoutInSeconds <UInt32>] [-IsGuiApplication]
 [-NoRedirectOutput] [-MergeStdErrAndStdOut] [-OutputDirectory <String>] [-NoTerminateOnTimeout]
 [-AdditionalEnvironmentVariables <IDictionary>] [-WaitOption <WaitType>] [-SecureArgumentList] [-PassThru]
 [<CommonParameters>]

Username

Start-ADTProcessAsUser -FilePath <String> [-ArgumentList <String[]>] [-WorkingDirectory <String>] [-HideWindow]
 [-ProcessCreationFlags <CREATE_PROCESS>] [-InheritEnvironmentVariables] [-Wait] -Username <String>
 [-UseLinkedAdminToken] [-SuccessExitCodes <Int32[]>] [-ConsoleTimeoutInSeconds <UInt32>] [-IsGuiApplication]
 [-NoRedirectOutput] [-MergeStdErrAndStdOut] [-OutputDirectory <String>] [-NoTerminateOnTimeout]
 [-AdditionalEnvironmentVariables <IDictionary>] [-WaitOption <WaitType>] [-SecureArgumentList] [-PassThru]
 [<CommonParameters>]

DESCRIPTION

Invokes a process from SYSTEM in another user's session.

EXAMPLES

EXAMPLE 1

Start-ADTProcessAsUser -FilePath "$($adtSession.DirFiles)\setup.exe" -ArgumentList '/S' -SuccessExitCodes 0, 500

PARAMETERS

-FilePath

Path to the executable to invoke.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ArgumentList

Arguments for the invoked executable.

Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-WorkingDirectory

The 'start-in' directory for the invoked executable.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-HideWindow

Specifies whether the window should be hidden or not.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-ProcessCreationFlags

One or more flags to control the process's invocation.

Type: CREATE_PROCESS
Parameter Sets: (All)
Aliases:
Accepted values: DEBUG_PROCESS, DEBUG_ONLY_THIS_PROCESS, CREATE_SUSPENDED, DETACHED_PROCESS, CREATE_NEW_CONSOLE, NORMAL_PRIORITY_CLASS, IDLE_PRIORITY_CLASS, HIGH_PRIORITY_CLASS, REALTIME_PRIORITY_CLASS, CREATE_NEW_PROCESS_GROUP, CREATE_UNICODE_ENVIRONMENT, CREATE_SEPARATE_WOW_VDM, CREATE_SHARED_WOW_VDM, BELOW_NORMAL_PRIORITY_CLASS, ABOVE_NORMAL_PRIORITY_CLASS, INHERIT_PARENT_AFFINITY, CREATE_PROTECTED_PROCESS, EXTENDED_STARTUPINFO_PRESENT, PROCESS_MODE_BACKGROUND_BEGIN, PROCESS_MODE_BACKGROUND_END, CREATE_SECURE_PROCESS, CREATE_BREAKAWAY_FROM_JOB, CREATE_PRESERVE_CODE_AUTHZ_LEVEL, CREATE_DEFAULT_ERROR_MODE, CREATE_NO_WINDOW

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-InheritEnvironmentVariables

Specifies whether the process should inherit the user's environment state.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Wait

Specifies whether to wait for the invoked excecutable to finish.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Username

The username of the user's session to invoke the executable in.

Type: String
Parameter Sets: Username
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-SessionId

The session ID of the user to invoke the executable in.

Type: UInt32
Parameter Sets: SessionId
Aliases:

Required: True
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-AllActiveUserSessions

Specifies that the executable should be invoked in all active sessions.

Type: SwitchParameter
Parameter Sets: AllActiveUserSessions
Aliases:

Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-UseLinkedAdminToken

Specifies that an admin token (if available) should be used for the invocation.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-SuccessExitCodes

Specifies one or more exit codes that the function uses to consider the invocation successful.

Type: Int32[]
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ConsoleTimeoutInSeconds

Specifies the timeout in seconds to wait for a console application to finish its task.

Type: UInt32
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-IsGuiApplication

Indicates that the executed application is a GUI-based app, not a console-based app.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-NoRedirectOutput

Specifies that stdout/stderr output should not be redirected to file.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-MergeStdErrAndStdOut

Specifies that the stdout/stderr streams should be merged into a single output.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-OutputDirectory

Specifies the output directory for the redirected stdout/stderr streams.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-NoTerminateOnTimeout

Specifies that the process shouldn't terminate on timeout.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-AdditionalEnvironmentVariables

Specifies additional environment variables to inject into the user's session.

Type: IDictionary
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-WaitOption

Specifies the wait type to use when waiting for an invoked executable to finish.

Type: WaitType
Parameter Sets: (All)
Aliases:
Accepted values: WaitForAny, WaitForAll

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-SecureArgumentList

Hides all parameters passed to the executable from the Toolkit log file.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-PassThru

If NoWait is not specified, returns an object with ExitCode, STDOut and STDErr output from the process. If NoWait is specified, returns an object with Id, Handle and ProcessName.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
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

System.Threading.Tasks.Task[System.Int32]

Returns a task object indicating the process's result.

NOTES

An active ADT session is NOT required to use this function.

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/Start-ADTProcessAsUser