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.39--> <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:syntaxItem parametersetname="Default"> <!--NAME: Default--> <maml:name>Write-PSFMessage</maml:name> <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> <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> <dev:type> <maml:name>System.Bool</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Breakpoint</maml:name> <maml:description> <maml:para>The breakpoint switch enables breaking on this debug message. By default, Write-PSFMessage will not interrupt execution if the -Debug parameter is specified, even when writing to the debug stream.</maml:para> </maml:description> <dev:type> <maml:name /> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> </command:syntaxItem> </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:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Breakpoint</maml:name> <maml:description> <maml:para>The breakpoint switch enables breaking on this debug message. By default, Write-PSFMessage will not interrupt execution if the -Debug parameter is specified, even when writing to the debug stream.</maml:para> </maml:description> <dev:type> <maml:name /> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> </command:parameters> <command:examples> <!--Examples--> <command:example> <maml:title>Example 1: Simple verbose message</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>Write-PSFMessage -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> <maml:para> _</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2: Writing a warning</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>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> <maml:para> _</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 3: Including extra information</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>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> <maml:para> _</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 4: Writing a message once only</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>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> <maml:para> _</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 5: Passing on exceptions</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>Write-PSFMessage -Level Warning -Message "Failed to retrieve additional network adapter information from $computer" -Target $computer -ErrorRecord $_</dev:code> <dev:remarks> <maml:para>This example assumes to be executed within a catch block. 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> <maml:para> -</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 6: Overriding Error Messages</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>Write-PSFMessage -Level Warning -Message "Failed to change network adapter settings, this command requires elevation. Restart your console as admin and try again" -Target $computer -ErrorRecord $_ -OverrideExceptionMessage</dev:code> <dev:remarks> <maml:para>Similar to Example 5, this shows how to write an error message with debugging information attached. The key difference here is that this assumes the error message has been properly interpreted for the end user, making it no longer desirable to automatically append the exception message.</maml:para> <maml:para> _</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 7: Tagging messages</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>Write-PSFMessage -Message "Connecting to $computer" -Target $computer -Tag 'connect','CIM'</dev:code> <dev:remarks> <maml:para>This shows how to use the -Tag parameter to add tags to a message. These can later be used with Get-PSFMessage or the logs to filter messages by. Tags can also be used to apply rules to, such as where to log to.</maml:para> <maml:para> _</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 8: Overriding debugging information</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>Write-PSFMessage -Message "Connecting to $computer" -Line 21 -File "Connect-Computer.ps1"</dev:code> <dev:remarks> <maml:para>The message system contains a lot of extra information that can be useful when debugging, such as file and line it was written from. However depending on your build and import practices, those might not be a perfect fit for you. Thus it is possible to override them, to aid with debugging your code.</maml:para> <maml:para> _</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 9: Explicitly specifying meta information</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>Write-PSFMessage -Message "Doing something" -FunctionName "Get-BeerParallel" -ModuleName "BeerFactory"</dev:code> <dev:remarks> <maml:para>By default, Write-PSFMessage automatically gathers module and function information. However, this doesn't always work, for example on scriptblocks that are run in separate runspaces. For those instances, you can manually specify the command to display. Note: Logging is runspace-safe, so you can use this command parallel in multiple runspaces. All messages from all runspaces are visible with Get-PSFMessage.</maml:para> <maml:para> -</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 10: Supporting Debugging</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>Write-PSFMessage -Level Debug -Message "Executing SQL Query 'SELECT * FROM table'" -Breakpoint</dev:code> <dev:remarks> <maml:para>By using the breakpoint parameter in this message, PowerShell will break into the debugger at this position, if the command writing this message is run with the -Debug parameter. By default, Write-PSFMessage will never interrupt execution when -Debug is specified, in contrast to how Write-Debug acts.</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--> <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>Set-PSFConfig</command:name> <maml:description> <maml:para>Sets configuration entries.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Set</command:verb> <command:noun>PSFConfig</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>This function creates or changes configuration values. These can be used to provide dynamic configuration information outside the PowerShell variable system.</maml:para> </maml:description> <command:syntax> <!--Parameter Sets--> <command:syntaxItem parametersetname="FullName"> <!--NAME: FullName--> <maml:name>Set-PSFConfig</maml:name> <command:parameter required="true" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>FullName</maml:name> <maml:description> <maml:para>The full name of a configuration element. Must be namespaced <Module>.<Name>. The name can have any number of sub-segments, in order to better group configurations thematically.</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>Value</maml:name> <maml:description> <maml:para>The value to assign to the named configuration element.</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>Description</maml:name> <maml:description> <maml:para>Using this, the configuration setting is given a description, making it easier for a user to comprehend, what a specific setting is for.</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>Validation</maml:name> <maml:description> <maml:para>The name of the validation script used for input validation. These can be used to validate make sure that input is of the proper data type. New validation scripts can be registered using Register-PSFConfigValidation</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ScriptBlock</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Handler</maml:name> <maml:description> <maml:para>A scriptblock that is executed when a value is being set. Is only executed if the validation was successful (assuming there was a validation, of course)</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ScriptBlock</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Hidden</maml:name> <maml:description> <maml:para>Setting this parameter hides the configuration from casual discovery. Configurations with this set will only be returned by Get-Config, if the parameter "-Force" is used. This should be set for all system settings a user should have no business changing (e.g. for Infrastructure related settings such as mail server).</maml:para> </maml:description> <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>Default</maml:name> <maml:description> <maml:para>Setting this parameter causes the system to treat this configuration as a default setting. If the configuration already exists, no changes will be performed. Useful in scenarios where for some reason it is not practical to automatically set defaults before loading userprofiles.</maml:para> </maml:description> <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>Initialize</maml:name> <maml:description> <maml:para>Use this when setting configurations as part of module import. When initializing a configuration, it will only do a thing if the configuration hasn't already been initialized (So if you load the module multiple times or in multiple runspaces, it won't make a difference) Also, if there already was a non-initialized setting set for a given configuration, it will then try to set the old value again. This value will be processed by handlers, if any are set.</maml:para> </maml:description> <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>DisableValidation</maml:name> <maml:description> <maml:para>This parameters disables the input validation - if any - when processing a setting. Normally this shouldn't be circumvented, but just in case, it can be disabled.</maml:para> </maml:description> <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>DisableHandler</maml:name> <maml:description> <maml:para>This parameter disables the configuration handlers. Configuration handlers are designed to automatically process input set to a config value, in addition to writing the value. In many cases, this is used to improve performance, by forking the value location also to a static C#-field, which is then used, rather than searching a Hashtable. Normally these shouldn't be circumvented, but just in case, it can be disabled.</maml:para> </maml:description> <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>EnableException</maml:name> <maml:description> <maml:para>Replaces user friendly yellow warnings with bloody red exceptions of doom! Use this if you want the function to throw terminating errors you want to catch.</maml:para> </maml:description> <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>SimpleExport</maml:name> <maml:description> <maml:para>Enabling this will cause the module to use friendly json notation on export to file. This may result in loss of data precision, but makes it easier to edit settings in file.</maml:para> </maml:description> <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>ModuleExport</maml:name> <maml:description> <maml:para>Using 'Export-PSFConfig -ModuleName <ModuleName>' settings flagged with this switch will be exported to a default path if they have been changed from the initial default value.</maml:para> </maml:description> <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>PassThru</maml:name> <maml:description> <maml:para>Return the changed configuration setting object.</maml:para> </maml:description> <dev:type> <maml:name>Switch</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> </command:syntaxItem> <command:syntaxItem parametersetname="Module"> <!--NAME: Module--> <maml:name>Set-PSFConfig</maml:name> <command:parameter required="true" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Name</maml:name> <maml:description> <maml:para>Name of the configuration entry. If an entry of exactly this non-casesensitive name already exists, its value will be overwritten. Duplicate names across different modules are possible and will be treated separately. If a name contains namespace notation and no module is set, the first namespace element will be used as module instead of name. Example: -Name "Nordwind.Server" Is Equivalent to -Name "Server" -Module "Nordwind"</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>Module</maml:name> <maml:description> <maml:para>This allows grouping configuration elements into groups based on the module/component they serve. If this parameter is not set, the configuration element must have a module name in the name parameter (the first segment will be taken, irrespective of whether that makes sense).</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>Value</maml:name> <maml:description> <maml:para>The value to assign to the named configuration element.</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>Description</maml:name> <maml:description> <maml:para>Using this, the configuration setting is given a description, making it easier for a user to comprehend, what a specific setting is for.</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>Handler</maml:name> <maml:description> <maml:para>A scriptblock that is executed when a value is being set. Is only executed if the validation was successful (assuming there was a validation, of course)</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ScriptBlock</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Hidden</maml:name> <maml:description> <maml:para>Setting this parameter hides the configuration from casual discovery. Configurations with this set will only be returned by Get-Config, if the parameter "-Force" is used. This should be set for all system settings a user should have no business changing (e.g. for Infrastructure related settings such as mail server).</maml:para> </maml:description> <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>Validation</maml:name> <maml:description> <maml:para>The name of the validation script used for input validation. These can be used to validate make sure that input is of the proper data type. New validation scripts can be registered using Register-PSFConfigValidation</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ScriptBlock</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Default</maml:name> <maml:description> <maml:para>Setting this parameter causes the system to treat this configuration as a default setting. If the configuration already exists, no changes will be performed. Useful in scenarios where for some reason it is not practical to automatically set defaults before loading userprofiles.</maml:para> </maml:description> <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>Initialize</maml:name> <maml:description> <maml:para>Use this when setting configurations as part of module import. When initializing a configuration, it will only do a thing if the configuration hasn't already been initialized (So if you load the module multiple times or in multiple runspaces, it won't make a difference) Also, if there already was a non-initialized setting set for a given configuration, it will then try to set the old value again. This value will be processed by handlers, if any are set.</maml:para> </maml:description> <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>DisableValidation</maml:name> <maml:description> <maml:para>This parameters disables the input validation - if any - when processing a setting. Normally this shouldn't be circumvented, but just in case, it can be disabled.</maml:para> </maml:description> <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>DisableHandler</maml:name> <maml:description> <maml:para>This parameter disables the configuration handlers. Configuration handlers are designed to automatically process input set to a config value, in addition to writing the value. In many cases, this is used to improve performance, by forking the value location also to a static C#-field, which is then used, rather than searching a Hashtable. Normally these shouldn't be circumvented, but just in case, it can be disabled.</maml:para> </maml:description> <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>EnableException</maml:name> <maml:description> <maml:para>Replaces user friendly yellow warnings with bloody red exceptions of doom! Use this if you want the function to throw terminating errors you want to catch.</maml:para> </maml:description> <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>SimpleExport</maml:name> <maml:description> <maml:para>Enabling this will cause the module to use friendly json notation on export to file. This may result in loss of data precision, but makes it easier to edit settings in file.</maml:para> </maml:description> <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>ModuleExport</maml:name> <maml:description> <maml:para>Using 'Export-PSFConfig -ModuleName <ModuleName>' settings flagged with this switch will be exported to a default path if they have been changed from the initial default value.</maml:para> </maml:description> <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>PassThru</maml:name> <maml:description> <maml:para>Return the changed configuration setting object.</maml:para> </maml:description> <dev:type> <maml:name>Switch</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> </command:syntaxItem> <command:syntaxItem parametersetname="Persisted"> <!--NAME: Persisted--> <maml:name>Set-PSFConfig</maml:name> <command:parameter required="true" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>FullName</maml:name> <maml:description> <maml:para>The full name of a configuration element. Must be namespaced <Module>.<Name>. The name can have any number of sub-segments, in order to better group configurations thematically.</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>Description</maml:name> <maml:description> <maml:para>Using this, the configuration setting is given a description, making it easier for a user to comprehend, what a specific setting is for.</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>Validation</maml:name> <maml:description> <maml:para>The name of the validation script used for input validation. These can be used to validate make sure that input is of the proper data type. New validation scripts can be registered using Register-PSFConfigValidation</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ScriptBlock</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Handler</maml:name> <maml:description> <maml:para>A scriptblock that is executed when a value is being set. Is only executed if the validation was successful (assuming there was a validation, of course)</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ScriptBlock</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Hidden</maml:name> <maml:description> <maml:para>Setting this parameter hides the configuration from casual discovery. Configurations with this set will only be returned by Get-Config, if the parameter "-Force" is used. This should be set for all system settings a user should have no business changing (e.g. for Infrastructure related settings such as mail server).</maml:para> </maml:description> <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>Default</maml:name> <maml:description> <maml:para>Setting this parameter causes the system to treat this configuration as a default setting. If the configuration already exists, no changes will be performed. Useful in scenarios where for some reason it is not practical to automatically set defaults before loading userprofiles.</maml:para> </maml:description> <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>Initialize</maml:name> <maml:description> <maml:para>Use this when setting configurations as part of module import. When initializing a configuration, it will only do a thing if the configuration hasn't already been initialized (So if you load the module multiple times or in multiple runspaces, it won't make a difference) Also, if there already was a non-initialized setting set for a given configuration, it will then try to set the old value again. This value will be processed by handlers, if any are set.</maml:para> </maml:description> <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>DisableValidation</maml:name> <maml:description> <maml:para>This parameters disables the input validation - if any - when processing a setting. Normally this shouldn't be circumvented, but just in case, it can be disabled.</maml:para> </maml:description> <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>DisableHandler</maml:name> <maml:description> <maml:para>This parameter disables the configuration handlers. Configuration handlers are designed to automatically process input set to a config value, in addition to writing the value. In many cases, this is used to improve performance, by forking the value location also to a static C#-field, which is then used, rather than searching a Hashtable. Normally these shouldn't be circumvented, but just in case, it can be disabled.</maml:para> </maml:description> <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>EnableException</maml:name> <maml:description> <maml:para>Replaces user friendly yellow warnings with bloody red exceptions of doom! Use this if you want the function to throw terminating errors you want to catch.</maml:para> </maml:description> <dev:type> <maml:name>Switch</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="true" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>PersistedValue</maml:name> <maml:description> <maml:para>In most circumstances an internal parameter. Applies the serialized value to a setting. Used for restoring data from configuration files that should only be deserialized when the module consuming it is already imported.</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>PersistedType</maml:name> <maml:description> <maml:para>In most circumstances an internal parameter. Paired with PersistedValue, used to specify the data type of the serialized object set in its serialized state.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSFramework.Configuration.ConfigurationValueType</command:parameterValue> <dev:type> <maml:name>PSFramework.Configuration.ConfigurationValueType</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>SimpleExport</maml:name> <maml:description> <maml:para>Enabling this will cause the module to use friendly json notation on export to file. This may result in loss of data precision, but makes it easier to edit settings in file.</maml:para> </maml:description> <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>ModuleExport</maml:name> <maml:description> <maml:para>Using 'Export-PSFConfig -ModuleName <ModuleName>' settings flagged with this switch will be exported to a default path if they have been changed from the initial default value.</maml:para> </maml:description> <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>PassThru</maml:name> <maml:description> <maml:para>Return the changed configuration setting object.</maml:para> </maml:description> <dev:type> <maml:name>Switch</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <!--All Parameters--> <command:parameter required="true" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>FullName</maml:name> <maml:description> <maml:para>The full name of a configuration element. Must be namespaced <Module>.<Name>. The name can have any number of sub-segments, in order to better group configurations thematically.</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="true" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Name</maml:name> <maml:description> <maml:para>Name of the configuration entry. If an entry of exactly this non-casesensitive name already exists, its value will be overwritten. Duplicate names across different modules are possible and will be treated separately. If a name contains namespace notation and no module is set, the first namespace element will be used as module instead of name. Example: -Name "Nordwind.Server" Is Equivalent to -Name "Server" -Module "Nordwind"</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>Module</maml:name> <maml:description> <maml:para>This allows grouping configuration elements into groups based on the module/component they serve. If this parameter is not set, the configuration element must have a module name in the name parameter (the first segment will be taken, irrespective of whether that makes sense).</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>Value</maml:name> <maml:description> <maml:para>The value to assign to the named configuration element.</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>Description</maml:name> <maml:description> <maml:para>Using this, the configuration setting is given a description, making it easier for a user to comprehend, what a specific setting is for.</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>Validation</maml:name> <maml:description> <maml:para>The name of the validation script used for input validation. These can be used to validate make sure that input is of the proper data type. New validation scripts can be registered using Register-PSFConfigValidation</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ScriptBlock</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Handler</maml:name> <maml:description> <maml:para>A scriptblock that is executed when a value is being set. Is only executed if the validation was successful (assuming there was a validation, of course)</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.ScriptBlock</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Hidden</maml:name> <maml:description> <maml:para>Setting this parameter hides the configuration from casual discovery. Configurations with this set will only be returned by Get-Config, if the parameter "-Force" is used. This should be set for all system settings a user should have no business changing (e.g. for Infrastructure related settings such as mail server).</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>Default</maml:name> <maml:description> <maml:para>Setting this parameter causes the system to treat this configuration as a default setting. If the configuration already exists, no changes will be performed. Useful in scenarios where for some reason it is not practical to automatically set defaults before loading userprofiles.</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>Initialize</maml:name> <maml:description> <maml:para>Use this when setting configurations as part of module import. When initializing a configuration, it will only do a thing if the configuration hasn't already been initialized (So if you load the module multiple times or in multiple runspaces, it won't make a difference) Also, if there already was a non-initialized setting set for a given configuration, it will then try to set the old value again. This value will be processed by handlers, if any are set.</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>DisableValidation</maml:name> <maml:description> <maml:para>This parameters disables the input validation - if any - when processing a setting. Normally this shouldn't be circumvented, but just in case, it can be disabled.</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>DisableHandler</maml:name> <maml:description> <maml:para>This parameter disables the configuration handlers. Configuration handlers are designed to automatically process input set to a config value, in addition to writing the value. In many cases, this is used to improve performance, by forking the value location also to a static C#-field, which is then used, rather than searching a Hashtable. Normally these shouldn't be circumvented, but just in case, it can be disabled.</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>EnableException</maml:name> <maml:description> <maml:para>Replaces user friendly yellow warnings with bloody red exceptions of doom! Use this if you want the function to throw terminating errors you want to catch.</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="true" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>PersistedValue</maml:name> <maml:description> <maml:para>In most circumstances an internal parameter. Applies the serialized value to a setting. Used for restoring data from configuration files that should only be deserialized when the module consuming it is already imported.</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>PersistedType</maml:name> <maml:description> <maml:para>In most circumstances an internal parameter. Paired with PersistedValue, used to specify the data type of the serialized object set in its serialized state.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">PSFramework.Configuration.ConfigurationValueType</command:parameterValue> <dev:type> <maml:name>PSFramework.Configuration.ConfigurationValueType</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>SimpleExport</maml:name> <maml:description> <maml:para>Enabling this will cause the module to use friendly json notation on export to file. This may result in loss of data precision, but makes it easier to edit settings in file.</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>ModuleExport</maml:name> <maml:description> <maml:para>Using 'Export-PSFConfig -ModuleName <ModuleName>' settings flagged with this switch will be exported to a default path if they have been changed from the initial default value.</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>PassThru</maml:name> <maml:description> <maml:para>Return the changed configuration setting object.</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:parameters> <command:returnValues> <!--Outputs--> <command:returnValue> <dev:type> <maml:name>PSFramework.Configuration.Config</maml:name> <maml:uri></maml:uri> </dev:type> <maml:description> <maml:para /> </maml:description> </command:returnValue> </command:returnValues> <command:examples> <!--Examples--> <command:example> <maml:title>Example 1: Simple </maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>C:\PS> Set-PSFConfig -FullName 'MyModule.User' -Value "Friedrich"</dev:code> <dev:remarks> <maml:para>Creates or updates a configuration entry under the module "MyModule" named "User" with the value "Friedrich"</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2: Module Definition</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>C:\PS> Set-PSFConfig -Name 'mymodule.User' -Value "Friedrich" -Description "The user under which the show must go on." -Handler $scriptBlock -Initialize -Validation String</dev:code> <dev:remarks> <maml:para>Creates a configuration entry ... - Named "mymodule.user" - With the value "Friedrich" - It adds a description as noted - It registers the scriptblock stored in $scriptBlock as handler - It initializes the script. This block only executes the first time a it is run like this. Subsequent calls will be ignored. - It registers the basic string input type validator This is the default example for modules using the configuration system. Note: While the -Handler parameter is optional, it is important to add it at the initial initialize call, if you are planning to add it. Only then will the system validate previous settings (such as what a user might have placed in his user profile)</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 3: Hiding things</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>C:\PS> Set-PSFConfig 'Company' 'ConfigLink' 'https://www.example.com/config.xml' -Hidden</dev:code> <dev:remarks> <maml:para>Creates a configuration entry named "ConfigLink" in the "Company" module with the value 'https://www.example.com/config.xml'. This entry is hidden from casual discovery using Get-PSFConfig.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 4: Default Settings</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>C:\PS> Set-PSFConfig -FullName 'Network.Firewall' -Value '10.0.0.2' -Default</dev:code> <dev:remarks> <maml:para>Creates a configuration entry named "Firewall" in the "Network" module with the value '10.0.0.2' This is only set, if the setting does not exist yet. If it does, this command will apply no changes.</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/Set-PSFConfig.html</maml:uri> </maml:navigationLink> </maml:relatedLinks> </command:command> <!--Edited with: SAPIEN PowerShell HelpWriter 2018 v2.2.39--> <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>Remove-PSFNull</command:name> <maml:description> <maml:para>Filters out null objects.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Remove</command:verb> <command:noun>PSFNull</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>This cmdlet can be used to filter out $null objects, empty collections and empty strings from the pipeline.</maml:para> </maml:description> <command:syntax> <!--Parameter Sets--> <command:syntaxItem> <maml:name>Remove-PSFNull</maml:name> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The items to filter</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>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>AllowEmptyCollections</maml:name> <maml:description> <maml:para>By default, empty collections are dropped from the output. Using this switch, they are passe along.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>AllowEmptyStrings</maml:name> <maml:description> <maml:para>By default, empty strings are discarded. Setting this switch causes them to be passed through instead.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Enumerate</maml:name> <maml:description> <maml:para>By default, output is not enumerated (Lists are sent along the pipeline as Lists, not individual items). If Remove-PSFNull should enumerate output after all, set this switch.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <!--All Parameters--> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The items to filter</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>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>AllowEmptyCollections</maml:name> <maml:description> <maml:para>By default, empty collections are dropped from the output. Using this switch, they are passe along.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>AllowEmptyStrings</maml:name> <maml:description> <maml:para>By default, empty strings are discarded. Setting this switch causes them to be passed through instead.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="false" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Enumerate</maml:name> <maml:description> <maml:para>By default, output is not enumerated (Lists are sent along the pipeline as Lists, not individual items). If Remove-PSFNull should enumerate output after all, set this switch.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> </command:parameters> <command:examples> <!--Examples--> <command:example> <maml:title>Example 1: Sweeping the Pipeline</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>C:\PS> Get-Something | Remove-PSFNull | Do-Something</dev:code> <dev:remarks> <maml:para>In this example, Remove-PSFNull cleans up the pipeline from null-equivalent objects before passing output along to Do-Something</maml:para> </dev:remarks> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Documentation:</maml:linkText> <maml:uri>http://psframework.org/documentation/commands/PSFramework/Remove-PSFNull.html</maml:uri> </maml:navigationLink> <!--Links--> </maml:relatedLinks> </command:command> <!--Edited with: SAPIEN PowerShell HelpWriter 2018 v2.2.39--> <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"> <!--Command--> <command:details> <command:name>Test-PSFShouldProcess</command:name> <maml:description> <maml:para>Implements the shouldprocess question.</maml:para> </maml:description> <maml:copyright> <maml:para /> </maml:copyright> <command:verb>Test</command:verb> <command:noun>PSFShouldProcess</command:noun> <dev:version /> </command:details> <maml:description> <maml:para>This command can be used in other commands to implement the ShouldProcess question asked if using the command requires confirmation. This replaces / wraps the traditional ShouldProcess call, makes it easier to read in script and allows mocking it.</maml:para> </maml:description> <command:syntax> <!--Parameter Sets--> <command:syntaxItem parametersetname="Default"> <!--NAME: Default--> <maml:name>Test-PSFShouldProcess</maml:name> <command:parameter required="true" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>PSCmdlet</maml:name> <maml:description> <maml:para>The $PSCmdlet variable of the calling function. Used to ensure the actual prompt logic as intended is being used.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.PSCmdlet</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.PSCmdlet</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="true" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Target</maml:name> <maml:description> <maml:para>The target that is being processed.</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="true" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Action</maml:name> <maml:description> <maml:para>The action that will be performed on the target</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:syntaxItem> </command:syntax> <command:parameters> <!--All Parameters--> <command:parameter required="true" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>PSCmdlet</maml:name> <maml:description> <maml:para>The $PSCmdlet variable of the calling function. Used to ensure the actual prompt logic as intended is being used.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">System.Management.Automation.PSCmdlet</command:parameterValue> <dev:type> <maml:name>System.Management.Automation.PSCmdlet</maml:name> <maml:uri /> </dev:type> <dev:defaultValue /> </command:parameter> <command:parameter required="true" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Target</maml:name> <maml:description> <maml:para>The target that is being processed.</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="true" globbing="false" pipelineInput="False" variableLength="false" position="named"> <maml:name>Action</maml:name> <maml:description> <maml:para>The action that will be performed on the target</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:parameters> <command:examples> <!--Examples--> <command:example> <maml:title>Example 1: Basic Usage</maml:title> <maml:introduction> <maml:para /> </maml:introduction> <dev:code>if (Test-PSFShouldProcess -PSCmdlet $PSCmdlet -Target $item -Action "Performing some arbitrary action") { }</dev:code> <dev:remarks> <maml:para>This will test whether the user should be prompted for confirmation, will do so if necessary and report back the results.</maml:para> </dev:remarks> </command:example> </command:examples> <maml:relatedLinks> <maml:navigationLink> <maml:linkText>Online Documentation</maml:linkText> <maml:uri>http://psframework.org/documentation/commands/PSFramework/Test-PSFShouldProcess.html</maml:uri> </maml:navigationLink> <!--Links--> </maml:relatedLinks> </command:command> <!--Edited with: SAPIEN PowerShell HelpWriter 2018 v2.2.39--> </helpItems> |