Skip to content

xWindowsProcess

Jump to bottom Edit New page
dscbot edited this page Nov 11, 2023 · 1 revision

xWindowsProcess

Parameters

Parameter Attribute DataType Description Allowed Values
Path Key String The full path or file name to the process executable to start or stop.
Arguments Key String A string of arguments to pass to the process executable. Pass in an empty string if no arguments are needed.
Credential Write PSCredential The credential to run the process under.
Ensure Write String Indicates whether the process is present (running) or absent (not running). Present, Absent
StandardOutputPath Write String The path to write the standard output stream to.
StandardErrorPath Write String The path to write the standard error stream to.
StandardInputPath Write String The path to receive standard input from.
WorkingDirectory Write String The directory to run the processes under.
PagedMemorySize Read UInt64 The amount of paged memory, in bytes, allocated for the process.
NonPagedMemorySize Read UInt64 The amount of nonpaged memory, in bytes, allocated for the process.
VirtualMemorySize Read UInt64 The amount of virtual memory, in bytes, allocated for the process.
HandleCount Read SInt32 The number of handles opened by the process.
ProcessId Read SInt32 The unique identifier of the process.
ProcessCount Read SInt32 The number of instances of the given process that are currently running.

Description

Provides a mechanism to start and stop a Windows process.

Parameters

  • [String] Path (Key): The executable file of the process. This can be defined as either the full path to the file or as the name of the file if it is accessible through the environment path. Relative paths are not supported.
  • [String] Arguments (Key): A single string containing all the arguments to pass to the process. Pass in an empty string if no arguments are needed.
  • [PSCredential] Credential (Write): The credential of the user account to run the process under. If this user is from the local system, the StandardOutputPath, StandardInputPath, and WorkingDirectory parameters cannot be provided at the same time.
  • [String] Ensure (Write): Specifies whether or not the process should be running. To start the process, specify this property as Present. To stop the process, specify this property as Absent. { Present | Absent }.
  • [String] StandardOutputPath (Write): The file path to which to write the standard output from the process. Any existing file at this file path will be overwritten. This property cannot be specified at the same time as Credential when running the process as a local user.
  • [String] StandardErrorPath (Write): The file path to which to write the standard error output from the process. Any existing file at this file path will be overwritten.
  • [String] StandardInputPath (Write): The file path from which to receive standard input for the process. This property cannot be specified at the same time as Credential when running the process as a local user.
  • [String] WorkingDirectory (Write): The file path to the working directory under which to run the process. This property cannot be specified at the same time as Credential when running the process as a local user.

Examples

Example 1

#Requires -Module xPSDesiredStateConfiguration

<#
    .DESCRIPTION
        Configuration that starts a process that is provided in the given file
        path with the specified arguments.

    .PARAMETER FilePath
        The path to the executable file to start.

    .PARAMETER Argument
        The arguments for the process to start. Defaults to no argument.

    .EXAMPLE
        xWindowsProcess_StartProcess_Config -FilePath 'C:\WINDOWS\system32\PING.EXE' -Argument '-t localhost'

        Compiles a configuration that starts a process that continuously ping
        localhost, and monitors that the process 'ping' is always started.
#>
Configuration xWindowsProcess_StartProcess_Config
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $FilePath,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $Argument
    )

    Import-DscResource -ModuleName xPSDesiredStateConfiguration

    Node localhost
    {
        xWindowsProcess StartProcess
        {
            Path      = $FilePath
            Arguments = $Argument
            Ensure    = 'Present'
        }
    }
}

Example 2

#Requires -Module xPSDesiredStateConfiguration

<#
    .DESCRIPTION
        Configuration that starts a process under the given credential, that is
        provided in the given file path with the specified arguments.

    .PARAMETER FilePath
        The path to the executable file to start.

    .PARAMETER Argument
        The arguments for the process to start. Defaults to no argument.

    .PARAMETER Credential
        Credential to start the process under.

    .NOTES
        To use the sample(s) with credentials, see blog at:
        http://blogs.msdn.com/b/powershell/archive/2014/01/31/want-to-secure-credentials-in-windows-powershell-desired-state-configuration.aspx

    .EXAMPLE
        xWindowsProcess_StartProcessUnderUser_Config -FilePath 'C:\WINDOWS\system32\PING.EXE' -Argument '-t localhost' -Credential (Get-Credential)

        Compiles a configuration that starts a 'ping' process under the given
        credential, that continuously ping localhost, and monitors that the
        process 'ping' is always started.
#>
Configuration xWindowsProcess_StartProcessUnderUser_Config
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $FilePath,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $Argument,

        [Parameter(Mandatory = $true)]
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.Credential()]
        $Credential
    )

    Import-DscResource -ModuleName xPSDesiredStateConfiguration

    Node localhost
    {
        xUser CreateUserAccount
        {
            Ensure   = 'Present'
            UserName = Split-Path -Path $Credential.UserName -Leaf
            Password = $Credential
        }

        xWindowsProcess StartProcessUnderUser
        {
            Path       = $FilePath
            Arguments  = $Argument
            Credential = $Credential
            Ensure     = 'Present'
        }
    }
}

Example 3

#Requires -Module xPSDesiredStateConfiguration

<#
    .DESCRIPTION
        Configuration that stops the process that is provided in the given file
        path, where the argument matches, and if the process is running.

    .PARAMETER FilePath
        The path to the executable file to (process) to stop.

    .PARAMETER Argument
        The arguments for the process to stop. Defaults to no argument.

    .NOTES
        The FilePath could be set to just the process name only if the number of
        returned processed is less than or equal to 8. If more than 8 processes
        are returned, another filter is used to optimize performance, and that
        filter needs the full path to the executable file.

    .EXAMPLE
        xWindowsProcess_StopProcess_Config -FilePath 'C:\WINDOWS\system32\PING.EXE' -Argument '-t localhost'

        Compiles a configuration that stops a 'ping' process if the process exist.
#>
Configuration xWindowsProcess_StopProcess_Config
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $FilePath,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $Argument
    )

    Import-DscResource -ModuleName xPSDesiredStateConfiguration

    Node localhost
    {
        xWindowsProcess StopProcess
        {
            Path      = $FilePath
            Arguments = $Argument
            Ensure    = 'Absent'
        }
    }
}

Example 4

#Requires -Module xPSDesiredStateConfiguration

<#
    .DESCRIPTION
        Configuration that stops the process under the given credential, that is
        provided in the given file path, where the argument matches, and if the
        process is running.

    .PARAMETER FilePath
        The path to the executable file to (process) to stop.

    .PARAMETER Argument
        The arguments for the process to stop. Defaults to no argument.

    .PARAMETER Credential
        Credential that the process is running under.

    .NOTES
        The FilePath could be set to just the process name only if the number of
        returned processed is less than or equal to 8. If more than 8 processes
        are returned, another filter is used to optimize performance, and that
        filter needs the full path to the executable file.

        To use the sample(s) with credentials, see blog at:
        http://blogs.msdn.com/b/powershell/archive/2014/01/31/want-to-secure-credentials-in-windows-powershell-desired-state-configuration.aspx

    .EXAMPLE
        xWindowsProcess_StopProcessUnderUser_Config -FilePath 'C:\WINDOWS\system32\PING.EXE' -Argument '-t localhost' -Credential (Get-Credential)

        Compiles a configuration that stops a 'ping' process under the given
        credential, if the process exist.
#>
Configuration xWindowsProcess_StopProcessUnderUser_Config
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $FilePath,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $Argument,

        [Parameter(Mandatory = $true)]
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.Credential()]
        $Credential
    )

    Import-DscResource -ModuleName xPSDesiredStateConfiguration

    Node localhost
    {
        xWindowsProcess StopProcess
        {
            Path       = $FilePath
            Arguments  = $Argument
            Credential = $Credential
            Ensure     = 'Absent'
        }
    }
}

xPSDesiredStateConfiguration Module

Clone this wiki locally