dbatoolsGet-DbaExternalProcess
View SourceSynopsis
Retrieves operating system processes spawned by SQL Server instances
Description
Identifies and returns all child processes created by SQL Server, such as those spawned by xp_cmdshell, BCP operations, SSIS packages, or other external utilities.
This is particularly useful when troubleshooting sessions with External Wait Types, where SQL Server is waiting for an external process to complete. When sessions appear hung with wait types like WAITFOR_RESULTS or EXTERNAL_SCRIPT_NETWORK_IO, this command helps identify the specific external processes that may be causing the delay.
The function queries WMI to find the SQL Server process (sqlservr.exe) and then locates all processes where SQL Server is the parent process, providing details about memory usage and resource consumption.
Syntax
Get-DbaExternalProcess
[-ComputerName] <DbaInstanceParameter[]>
[[-Credential] <PSCredential>]
[-EnableException]
[<CommonParameters>]
Examples
Example: 1
PS C:\> Get-DbaExternalProcess -ComputerName SERVER01, SERVER02
Gets OS processes created by SQL Server on SERVER01 and SERVER02
Required Parameters
-ComputerName
Specifies the SQL Server host computer(s) to check for external processes spawned by SQL Server.
Use this when troubleshooting hung sessions or investigating resource usage from processes like xp_cmdshell, BCP, or SSIS operations.
Accepts multiple computer names and SQL Server instance names with automatic computer resolution.
| Property | Value |
|---|---|
| Alias | |
| Required | True |
| Pipeline | true (ByValue) |
| Default Value |
Optional Parameters
-Credential
Allows you to login to $ComputerName using alternative credentials.
| Property | Value |
|---|---|
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
-EnableException
By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
This avoids overwhelming you with “sea of red” exceptions, but is inconvenient because it basically disables advanced scripting.
Using this switch turns this “nice by default” feature off and enables you to catch exceptions with your own try/catch.
| Property | Value |
|---|---|
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | False |
Outputs
PSCustomObject
Returns one object per external process spawned by SQL Server on each target computer. For servers with no child processes spawned by SQL Server, nothing is returned.
Properties:
- ComputerName: The name of the computer where the SQL Server process resides
- ProcessId: The operating system process ID of the child process (unsigned integer)
- Name: The executable name of the child process (e.g., cmd.exe, bcp.exe, DTExec.exe)
- HandleCount: The number of open handles held by the child process (unsigned integer)
- WorkingSetSize: Memory currently in use by the child process in bytes (unsigned long)
- VirtualSize: Total virtual address space reserved by the child process in bytes (unsigned long)
- CimObject: The underlying WMI process object providing full access to all Win32_Process properties
- Credential: The credential object used for the WMI connection (this property is typically not useful for analysis)