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-BreakpointCommand or Disable-BreakpointCommand 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-BreakpointCommand</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Enable-BreakpointCommand</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> </helpItems> |