< Back
Invoke-PSFProtectedCommand
Post
NAME Invoke-PSFProtectedCommand
SYNOPSIS
Combines should process, try/catch error handling and logging in one package.
SYNTAX
Invoke-PSFProtectedCommand -Action <String> [-Confirm] [-Continue] [-EnableException <Boolean>] [-PSCmdlet
<PSCmdlet>] -ScriptBlock <ScriptBlock> [-Target <Object>] [-WhatIf] [<CommonParameters>]
Invoke-PSFProtectedCommand -ActionString <String> [-ActionStringValues <Object[]>] [-Confirm] [-Continue]
[-EnableException <Boolean>] [-PSCmdlet <PSCmdlet>] -ScriptBlock <ScriptBlock> [-Target <Object>] [-WhatIf]
[<CommonParameters>]
DESCRIPTION
This command is designed to do away with the script code overhead of:
- Prompting for ShouldProcess if needed
- Including try/catch error handling for the purpose of the PSFramework opt-in exceptions concept
- Logging execution
As such it is intended to help produce more readable code in less time.
Note: This command can only be used from an advanced function unless specifying the -PSCmdlet parameter.
PARAMETERS
-Action <String>
The action that will be performed on the target.
Required? true
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-ActionString <String>
Localized string of the action that will be performed on the target. Omit the modulename in the string. For
more details on the PSFramework localization feature, see the help on Import-PSFLocalizedString.
Required? true
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-ActionStringValues <Object[]>
Specify values to format into the localization string specified. For more details on the PSFramework
localization feature, see the help on Import-PSFLocalizedString.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Confirm [<SwitchParameter>]
If this switch is enabled, you will be prompted for confirmation before executing any operations that change
state.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-Continue [<SwitchParameter>]
When execution fails, unless exceptions where opted into, this command will call continue, moving on with the
next item to process.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-EnableException <Boolean>
This parameters disables user-friendly warnings and enables the throwing of exceptions. This is less user
friendly, but allows catching exceptions in calling scripts.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-PSCmdlet <PSCmdlet>
This command will automatically pick up the $PSCmdlet variable of its caller. Use this parameter to override
this and specify what $PSCmdlet variable to use. The $PSCmdlet variable will be used for terminating
exceptions.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-ScriptBlock <ScriptBlock>
The actual scriptblock to execute. Make sure any errors you want to trigger failure are terminating.
Required? true
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Target <Object>
The target object to work against.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-WhatIf [<SwitchParameter>]
if this switch is enabled, no actions are performed but informational messages will be displayed that explain
what would happen if the command were to run.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
Keine
OUTPUTS
System.Object
NOTES
---------- Example 1 : Killing with maximum prejudice ----------
PS C:\\> Invoke-PSFProtectedCommand -Action "Doing Something" -Target $computer -ScriptBlock {
Get-Something -ComputerName $computer -ErrorAction Stop
} -EnableException $true
Invokes the specified scriptblock, honoring ShouldProcess, logging execution and potential failure. Failure will
lead to a terminating exception.
_
---------------- Example 2 : Killing it softly ----------------
PS C:\\> Invoke-PSFProtectedCommand -Action "Doing Something" -Target $computer -ScriptBlock {
Get-Something -ComputerName $computer -ErrorAction Stop
}
PS C:\\> if (Test-PSFFunctionInterrupt) { return }
Invokes the specified scriptblock, honoring ShouldProcess, logging execution and potential failure. Failure will
lead to a warning with the command terminating silently, unless the calling command's module opted into inheriting
the '-EnableException' parameter (in which case the caller of the command calling Invoke-PSFProtectedCommand gets
to pick whether this is throwing an exception or not)
RELATED LINKS
SYNOPSIS
Combines should process, try/catch error handling and logging in one package.
SYNTAX
Invoke-PSFProtectedCommand -Action <String> [-Confirm] [-Continue] [-EnableException <Boolean>] [-PSCmdlet
<PSCmdlet>] -ScriptBlock <ScriptBlock> [-Target <Object>] [-WhatIf] [<CommonParameters>]
Invoke-PSFProtectedCommand -ActionString <String> [-ActionStringValues <Object[]>] [-Confirm] [-Continue]
[-EnableException <Boolean>] [-PSCmdlet <PSCmdlet>] -ScriptBlock <ScriptBlock> [-Target <Object>] [-WhatIf]
[<CommonParameters>]
DESCRIPTION
This command is designed to do away with the script code overhead of:
- Prompting for ShouldProcess if needed
- Including try/catch error handling for the purpose of the PSFramework opt-in exceptions concept
- Logging execution
As such it is intended to help produce more readable code in less time.
Note: This command can only be used from an advanced function unless specifying the -PSCmdlet parameter.
PARAMETERS
-Action <String>
The action that will be performed on the target.
Required? true
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-ActionString <String>
Localized string of the action that will be performed on the target. Omit the modulename in the string. For
more details on the PSFramework localization feature, see the help on Import-PSFLocalizedString.
Required? true
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-ActionStringValues <Object[]>
Specify values to format into the localization string specified. For more details on the PSFramework
localization feature, see the help on Import-PSFLocalizedString.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Confirm [<SwitchParameter>]
If this switch is enabled, you will be prompted for confirmation before executing any operations that change
state.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-Continue [<SwitchParameter>]
When execution fails, unless exceptions where opted into, this command will call continue, moving on with the
next item to process.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-EnableException <Boolean>
This parameters disables user-friendly warnings and enables the throwing of exceptions. This is less user
friendly, but allows catching exceptions in calling scripts.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-PSCmdlet <PSCmdlet>
This command will automatically pick up the $PSCmdlet variable of its caller. Use this parameter to override
this and specify what $PSCmdlet variable to use. The $PSCmdlet variable will be used for terminating
exceptions.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-ScriptBlock <ScriptBlock>
The actual scriptblock to execute. Make sure any errors you want to trigger failure are terminating.
Required? true
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Target <Object>
The target object to work against.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-WhatIf [<SwitchParameter>]
if this switch is enabled, no actions are performed but informational messages will be displayed that explain
what would happen if the command were to run.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
Keine
OUTPUTS
System.Object
NOTES
---------- Example 1 : Killing with maximum prejudice ----------
PS C:\\> Invoke-PSFProtectedCommand -Action "Doing Something" -Target $computer -ScriptBlock {
Get-Something -ComputerName $computer -ErrorAction Stop
} -EnableException $true
Invokes the specified scriptblock, honoring ShouldProcess, logging execution and potential failure. Failure will
lead to a terminating exception.
_
---------------- Example 2 : Killing it softly ----------------
PS C:\\> Invoke-PSFProtectedCommand -Action "Doing Something" -Target $computer -ScriptBlock {
Get-Something -ComputerName $computer -ErrorAction Stop
}
PS C:\\> if (Test-PSFFunctionInterrupt) { return }
Invokes the specified scriptblock, honoring ShouldProcess, logging execution and potential failure. Failure will
lead to a warning with the command terminating silently, unless the calling command's module opted into inheriting
the '-EnableException' parameter (in which case the caller of the command calling Invoke-PSFProtectedCommand gets
to pick whether this is throwing an exception or not)
RELATED LINKS