en-us/PSFramework.dll-Help.xml
|
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<helpItems schema="maml" xmlns="http://msh"> <!--Edited with: SAPIEN PowerShell HelpWriter 2018 v2.2.38--> <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"> <!--TAG: HASCOMMONPARAMETERS--> <!--Command--> <command:details> <command:name>Write-PSFMessage</command:name> <maml:description> <maml:para>This function receives messages, then logs and reports them.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Write</command:verb> <command:noun>PSFMessage</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>This function receives messages, then logs and reports them. Other functions hand off all their information output for processing to this function.</maml:para> <maml:para>This function will then handle: - Warning output - Error management for non-terminating errors (For errors that terminate execution or continue on with the next object use "Stop-PSFFunction") - Logging - Verbose output - Message output to users</maml:para> <maml:para>For the complex description on how this works and how users and developers can influence it, run: Get-Help about_psf_message</maml:para> </maml:description> <command:syntax> <!--Parameter Sets--> </command:syntax> <command:parameters> <!--All Parameters--> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Level</maml:name> <maml:description> <maml:para>This parameter represents the verbosity of the message. The lower the number, the more important it is for a human user to read the message. By default, the levels are distributed like this: - 1-3 Direct verbose output to the user (using Write-Host) - 4-6 Output only visible when requesting extra verbosity (using Write-Verbose) - 1-9 Debugging information, written using Write-Debug</maml:para> <maml:para>In addition, it is possible to select the level "Warning" which moves the message out of the configurable range: The user will always be shown this message, unless he silences the entire verbosity.</maml:para> <maml:para>Possible levels: Critical (1), Important / Output / Host (2), Significant (3), VeryVerbose (4), Verbose (5), SomewhatVerbose (6), System (7), Debug (8), InternalComment (9), Warning (666) Either one of the strings or its respective number will do as input.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSFramework.Message.MessageLevel</command:parameterValue> <dev:type> <maml:name>PSFramework.Message.MessageLevel</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>[PSFramework.Message.MessageLevel]::Verbose</dev:defaultValue> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Message</maml:name> <maml:description> <maml:para>The message to write/log. The function name and timestamp will automatically be prepended.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Tag</maml:name> <maml:description> <maml:para>Tags to add to the message written. This allows filtering and grouping by category of message, targeting specific messages.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String[]</command:parameterValue> <dev:type> <maml:name>System.String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>FunctionName</maml:name> <maml:description> <maml:para>The name of the calling function. Will be automatically set, but can be overridden when necessary.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>ModuleName</maml:name> <maml:description> <maml:para>The name of the module, the calling function is part of. Will be automatically set, but can be overridden when necessary.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>File</maml:name> <maml:description> <maml:para>The file in which Write-PSFMessage was called. Will be automatically set, but can be overridden when necessary.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Line</maml:name> <maml:description> <maml:para>The line on which Write-PSFMessage was called. Will be automatically set, but can be overridden when necessary.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">int</command:parameterValue> <dev:type> <maml:name>int</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>ErrorRecord</maml:name> <maml:description> <maml:para>If an error record should be noted with the message, add the full record here. Especially designed for use with Warning-mode, it can legally be used in either mode. The error will be added to the $Error variable and enqued in the logging/debugging system.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ErrorRecord[]</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ErrorRecord[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Exception</maml:name> <maml:description> <maml:para>Allows specifying an inner exception as input object. This will be passed on to the logging and used for messages. When specifying both ErrorRecord AND Exception, Exception wins, but ErrorRecord is still used for record metadata.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Exception</command:parameterValue> <dev:type> <maml:name>System.Exception</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Once</maml:name> <maml:description> <maml:para>Setting this parameter will cause this function to write the message only once per session. The string passed here and the calling function's name are used to create a unique ID, which is then used to register the action in the configuration system. Thus will the lockout only be written if called once and not burden the system unduly. This lockout will be written as a hidden value, to see it use Get-PSFConfig -Force.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.String</command:parameterValue> <dev:type> <maml:name>System.String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>OverrideExceptionMessage</maml:name> <maml:description> <maml:para>Disables automatic appending of exception messages. Use in cases where you already have a speaking message interpretation and do not need the original message.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Switch</command:parameterValue> <dev:type> <maml:name>Switch</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Target</maml:name> <maml:description> <maml:para>Add the object the message is all about, in order to simplify debugging / troubleshooting. For example, when calling this from a function targeting a remote computer, the computername could be specified here, allowing all messages to easily be correlated to the object processed.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Object</command:parameterValue> <dev:type> <maml:name>System.Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>EnableException</maml:name> <maml:description> <maml:para>This parameters disables user-friendly warnings and enables the throwing of exceptions. This is less user friendly, but allows catching exceptions in calling scripts.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Bool</command:parameterValue> <dev:type> <maml:name>System.Bool</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> </command:parameters> <command:examples> <!--Examples--> <command:example> <maml:title>EXAMPLE 1</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>PS C:\> Write-PSFMessage -Level Verbose -Message "Connecting to $computer"</dev:code> <dev:remarks> <maml:para>Writes the message "Connecting to $computer" to verbose. Will also log the message.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>EXAMPLE 2</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>PS C:\> Write-PSFMessage -Level Warning -Message "Failed to retrieve additional network adapter information from $computer"</dev:code> <dev:remarks> <maml:para>Writes the message "Failed to retrieve additional network adapter information from $computer" as a warning. Will also log the message.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>EXAMPLE 3</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>PS C:\> Write-PSFMessage -Level Verbose -Message "Connecting to $computer" -Target $computer</dev:code> <dev:remarks> <maml:para>Writes the message "Connecting to $computer" to verbose. Includes the variable $computer in the message. This has no effect on the text shown but will be available for debugging purposes. Will also log the message.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>EXAMPLE 4</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>PS C:\> Write-PSFMessage -Level Host -Message "This command has been deprecated, use 'Get-NewExample' instead" -Once 'Get-Example'</dev:code> <dev:remarks> <maml:para>Writes the message "This command has been deprecated, use 'Get-NewExample' instead" to the screen. This message will only be shown once per powershell process. Will also log the message.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>EXAMPLE 5</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>PS C:\> Write-PSFMessage -Level Warning -Message "Failed to retrieve additional network adapter information from $computer" -Target $computer -ErrorRecord $_</dev:code> <dev:remarks> <maml:para>Writes the message "Failed to retrieve additional network adapter information from $computer" as a warning. Will also append the message of the exception to the text. Will also add the error record to the error log Will also log the message.</maml:para> </dev:remarks> </command:example> </command:examples> <maml:relatedLinks> <!--Links--> <maml:navigationLink> <maml:linkText>Online Documentation</maml:linkText> <maml:uri>http://psframework.org/documentation/commands/PSFramework/Write-PSFMessage.html</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <!--Edited with: SAPIEN PowerShell HelpWriter 2018 v2.2.38--> </helpItems> |