en-us/DebugPx.dll-Help.xml
|
<?xml version="1.0" encoding="utf-8"?><helpItems schema="maml">
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <!--Generated by PS Cmdlet Help Editor--> <command:details> <command:name>Invoke-IfDebug</command:name> <maml:description> <maml:para>Invokes a series of commands when in debug mode and sends any output those commands generate to the debug stream.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Invoke</command:verb> <command:noun>IfDebug</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The ifdebug command invokes a series of commands when in debug mode and sends any output that those commands generate to the debug stream.</maml:para> <maml:para>You can use the ifdebug command in a pipeline to output debug information related to objects as they are passed through the pipeline. When debug mode is disabled, the objects will simply be passed through without the debug commands being invoked.</maml:para> <maml:para>In order to enable debug mode in PowerShell, you either need to invoke the command you want to debug with the -Debug common parameter, or you need to set $DebugPreference to any value other than Ignore or SilentlyContinue.</maml:para> <maml:para>The ifdebug command allows command authors to include blocks of script that output debug information to the debug stream without concern that leaving those blocks of script in place will impact performance or generate confusing output when the command is used normally. This is very useful for support purposes, allowing command authors to gather very specific pieces of information during the invocation of a PowerShell command by simply instructing an end user to run the command with the -Debug switch.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-IfDebug</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0"> <maml:name>DebugScript</maml:name> <maml:description> <maml:para>The script block that will be invoked when debug mode is enabled.</maml:para> <maml:para>When the ifdebug command is used in a pipeline, you can use the $_ or $PSItem variables to reference the current item that was just received from the previous stage in the pipeline.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The object that was input to the command, either by value (using this parameter) or through the pipeline.</maml:para> <maml:para>When ifdebug is invoked while debug mode is disabled, input objects will be passed directly through to the next stage in the pipeline without any additional processing.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0"> <maml:name>DebugScript</maml:name> <maml:description> <maml:para>The script block that will be invoked when debug mode is enabled.</maml:para> <maml:para>When the ifdebug command is used in a pipeline, you can use the $_ or $PSItem variables to reference the current item that was just received from the previous stage in the pipeline.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri/> </dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The object that was input to the command, either by value (using this parameter) or through the pipeline.</maml:para> <maml:para>When ifdebug is invoked while debug mode is disabled, input objects will be passed directly through to the next stage in the pipeline without any additional processing.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri/> </dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri></maml:uri> <maml:description/> </dev:type> <maml:description> <maml:para /> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri></maml:uri> <maml:description/> </dev:type> <maml:description> <maml:para /> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors></command:terminatingErrors> <command:nonTerminatingErrors></command:nonTerminatingErrors> <maml:alertSet> <maml:title></maml:title> <maml:alert> <maml:para>The -Debug common parameter has been in PowerShell since version 1. It was originally designed to allow script authors to conditionally enter a nested prompt at a specific location when running a script. Using -Debug when invoking a command would result in the caller being prompted whenever a Write-Debug command was invoked. This would happen because $DebugPreference would be set to "Inquire" whenever -Debug was used.</maml:para> <maml:para>While this design worked for PowerShell 1.0, it is fundamentally flawed in PowerShell 2.0 and later where breakpoint support is available. Breakpoints allow script authors to control when they want a script to stop execution, and stopping execution is a script author activity, not a script consumer activity. All use of Write-Debug inside of commands would either have to be commented out or removed entirely before a command was shipped, unless the command author wanted end users to deal with debug mode when they invoked a command with -Debug.</maml:para> <maml:para>A better use case for -Debug would be to provide additional output that is useful when troubleshooting issues with a command, including object data that would normally not be output and that would make even a Verbose stream look busy. Unlike Verbose output, which is usually descriptive, Debug output is more often not, and it is only helpful to a command author when troubleshooting issues. The ifdebug command solves this need by providing a script block that will only be invoked if the command is either invoked with -Debug or if the $DebugPreference variable in a scope where the command is invoked is set to any value other than SilentlyContinue or Ignore. In these scenarios, $DebugPreference is set to Continue before the DebugScript is invoked, all output generated by the DebugScript is written to the Debug stream, and then $DebugPreference is set back to its original value once the DebugScript has completed. With this model, there is no need to remove an ifdebug command invocation from a script when it comes time to release it to customers.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <maml:introduction> <maml:paragraph>PS C:\></maml:paragraph> </maml:introduction> <dev:code>PS C:\> function Test-Debug { >> [CmdletBinding()] >> param() >> ifdebug { >> Write-Debug 'Anything you output here is sent to the debug stream.' >> 'Even ordinary strings and objects.' >> Get-Service wuauserv >> } >> } PS C:\> Test-Debug PS C:\> Test-Debug -Debug</dev:code> <dev:remarks> <maml:para>The first command in this example creates a function that includes some debug output. Then once that function is created, the second command invokes the function without using the -Debug parameter. No output is generated. Finally, the last command invokes the function with the -Debug parameter, and all of the output from the ifdebug block is written to the debug stream and displayed in the console.</maml:para> <maml:para /> <maml:para /> <maml:para></maml:para> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText> <maml:para /> </command:commandText> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <!--Generated by PS Cmdlet Help Editor--> <command:details> <command:name>Enter-Debugger</command:name> <maml:description> <maml:para>Enters the debugger by triggering a breakpoint at the current location.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Enter</command:verb> <command:noun>Debugger</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The breakpoint command enters the debugger by triggering a breakpoint at the current location, whether that location be in a script file or in an interactive prompt.</maml:para> <maml:para>Without the ConditionScript parameter, the breakpoint command will enter the debugger by triggering a breakpoint where it is invoked. You can also use the breakpoint command to conditionally enter the debugger by providing an expression in the ConditionScript parameter. If the ConditionScript parameter evaluates to True, then the execution will be suspended at a breakpoint. If the ConditionScript parameter evaluates to False, then execution will continue beyond the breakpoint command.</maml:para> <maml:para>You can use the breakpoint command in a pipeline. If the breakpoint command is used in a pipeline, it will break for each object that it receives from the previous stage in the pipeline, conditionally if the ConditionScript parameter is used. If the breakpoint command is disabled, the object will be passed down the pipeline to the next stage, allowing breakpoint commands to be left in place while you disable or enable them as required when developing your PowerShell solutions.</maml:para> <maml:para>When you are setting breakpoints with more complex conditions or for more rare scenarios such as intermittent issues that you can't put your finger on, it can be helpful to know more context about those breakpoints when they are hit. For these situations, you can specify a message that you want written directly to the host using the Message parameter. The message you provide will be output to the host just before PowerShell enters the debugger, but only if the breakpoint condition passes.</maml:para> <maml:para>You can enable or disable the breakpoint command at any time by invoking either the Enable-EnterDebuggerCommand or Disable-EnterDebuggerCommand commands.</maml:para> <maml:para>The breakpoint command will not cause PowerShell to enter the debugger unless the current process is interactive.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Enter-Debugger</maml:name> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0"> <maml:name>ConditionScript</maml:name> <maml:description> <maml:para>The condition under which PowerShell will enter the debugger at a breakpoint at the current location.</maml:para> <maml:para>When the breakpoint command is used in a pipeline, you can use the $_ or $PSItem variables to reference the current item that was just received from the previous stage in the pipeline.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named"> <maml:name>Message</maml:name> <maml:description> <maml:para>A message that you want output to the host when the breakpoint is triggered.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The object that was input to the command, either by value (using this parameter) or through the pipeline.</maml:para> <maml:para>If the breakpoint command is disabled when it is invoked in a pipeline, input objects will be passed directly through to the next stage in the pipeline without any additional processing.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0"> <maml:name>ConditionScript</maml:name> <maml:description> <maml:para>The condition under which PowerShell will enter the debugger at a breakpoint at the current location.</maml:para> <maml:para>When the breakpoint command is used in a pipeline, you can use the $_ or $PSItem variables to reference the current item that was just received from the previous stage in the pipeline.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri/> </dev:type> <dev:defaultValue>{$true}</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="true (ByValue)" position="named"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The object that was input to the command, either by value (using this parameter) or through the pipeline.</maml:para> <maml:para>If the breakpoint command is disabled when it is invoked in a pipeline, input objects will be passed directly through to the next stage in the pipeline without any additional processing.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri/> </dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="named"> <maml:name>Message</maml:name> <maml:description> <maml:para>A message that you want output to the host when the breakpoint is triggered.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri/> </dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri></maml:uri> <maml:description/> </dev:type> <maml:description> <maml:para /> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> <maml:uri></maml:uri> <maml:description/> </dev:type> <maml:description> <maml:para /> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors></command:terminatingErrors> <command:nonTerminatingErrors></command:nonTerminatingErrors> <maml:alertSet> <maml:title></maml:title> <maml:alert> <maml:para>It is recommended that the breakpoint alias be used in place of Enter-Debugger because it more clearly indicates the intent of the command. This is an exception to the normal rule recommendation to use command names in place of aliases in scripts; however, all breakpoint command invocations should be removed from scripts before they are officially released, so that shouldn't be an issue.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <maml:introduction> <maml:paragraph>PS C:\></maml:paragraph> </maml:introduction> <dev:code>PS C:\> Get-Service w* | breakpoint {$_.Name -eq 'wuauserv'} | Select-Object -ExpandProperty Name</dev:code> <dev:remarks> <maml:para>If the breakpoint command is enabled (it is enabled by default), this command will get a list of names of services whose name starts with "w". When the Windows Update service is received by the breakpoint command, Windows PowerShell will enter the debugger at that breakpoint. The name of that service, and any remaining services, will be output to the console when the debugger is used to either step or to resume execution.</maml:para> <maml:para /> <maml:para /> <maml:para></maml:para> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText> <maml:para /> </command:commandText> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <maml:introduction> <maml:paragraph>PS C:\></maml:paragraph> </maml:introduction> <dev:code>PS C:\> & { >> 'Before breakpoint' >> breakpoint >> 'After breakpoint' >> }</dev:code> <dev:remarks> <maml:para>This command will output the text "Before breakpoint" to the console. Then, when the breakpoint command is invoked, if the breakpoint command is enabled (the default), Windows PowerShell will enter the debugger at the breakpoint command. The text "After breakpoint" will be output to the console when the debugger is used to step or to continue execution of the command.</maml:para> <maml:para /> <maml:para /> <maml:para></maml:para> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText> <maml:para /> </command:commandText> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <maml:introduction> <maml:paragraph>PS C:\></maml:paragraph> </maml:introduction> <dev:code>PS C:\> breakpoint { >> $service = Get-Service wuauserv >> $service.Status -eq 'Stopped' >> } -Message "The Windows Update service has stopped! How did this happen?"</dev:code> <dev:remarks> <maml:para>This command causes PowerShell to enter the debugger at a breakpoint on that command, but only if the Windows Update service is in a stopped state. When PowerShell enters the debugger, the message "The Windows Update service has stopped! How did this happen?" will be written directly to the host. These messages may help understand what condition you are watching for on conditional breakpoints in more complex scripting scenarios.</maml:para> <maml:para /> <maml:para /> <maml:para></maml:para> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText> <maml:para /> </command:commandText> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Disable-EnterDebuggerCommand</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Enable-EnterDebuggerCommand</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <!--Generated by PS Cmdlet Help Editor--> <command:details> <command:name>Debug-Module</command:name> <maml:description> <maml:para>Enters the debugger from inside of a script module scope.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Debug</command:verb> <command:noun>Module</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>The Debug-Module command enters the debugger inside of a script module scope, enabling interactive inspection of a module state from within that module. Entering the debugger this way allows you to check the state of a module, including internal variables and their current values, and internal commands loaded into the module scope.</maml:para> <maml:para>Debug-Module will also temporarily change the current file system location to the base folder for the script module being debugged. This facilitates faster inspection and modification of files on disk using the command-line.</maml:para> <maml:para>If the module is not loaded already when Debug-Module is invoked, Debug-Module will load the module automatically.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Debug-Module</maml:name> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0"> <maml:name>Name</maml:name> <maml:description> <maml:para>The name of the script module where PowerShell will enter the debugger.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0"> <maml:name>Name</maml:name> <maml:description> <maml:para>The name of the script module where PowerShell will enter the debugger.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri/> </dev:type> <dev:defaultValue></dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> <maml:uri></maml:uri> <maml:description/> </dev:type> <maml:description> <maml:para /> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> <maml:uri></maml:uri> <maml:description/> </dev:type> <maml:description> <maml:para>This cmdlet does not generate any output.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <command:terminatingErrors></command:terminatingErrors> <command:nonTerminatingErrors></command:nonTerminatingErrors> <maml:alertSet> <maml:title></maml:title> <maml:alert> <maml:para>Debug-Module will not work when the module root scope has either of the System.Diagnostics.DebuggerHidden or System.Diagnostics.DebuggerStepThrough attributes.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <maml:introduction> <maml:paragraph>PS C:\></maml:paragraph> </maml:introduction> <dev:code>PS C:\> Debug-Module -Name DebugPx</dev:code> <dev:remarks> <maml:para>This command sets the current location to the base folder for the DebugPx module and enters the debugger from inside of the DebugPx script module scope.</maml:para> <maml:para /> <maml:para /> <maml:para></maml:para> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText> <maml:para /> </command:commandText> </command:commandLine> </command:commandLines> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <maml:introduction> <maml:paragraph>[DBG]: PS C:\>></maml:paragraph> </maml:introduction> <dev:code>[DBG]: PS C:\>> Get-Variable -Scope 0 | Where-Object {-not ($_.Options -band [System.Management.Automation.ScopedItemOptions]::AllScope)}</dev:code> <dev:remarks> <maml:para>Once you are in debugger inside of a module, this command allows you to retrieve all variables that are defined in the script scope (at the root) of that module.</maml:para> <maml:para /> <maml:para /> <maml:para></maml:para> </dev:remarks> <command:commandLines> <command:commandLine> <command:commandText> <maml:para /> </command:commandText> </command:commandLine> </command:commandLines> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Enter-Debugger</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-Module</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Import-Module</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-Location</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> </helpItems> |